Using Cloud Links a data owner registers a table or view for remote access for a selected audience, as defined by the data owner. The data is then made accessible to those with access granted at registration time. No further actions are required to set up Cloud Links, and whoever is supposed to see and access your data is able to discover and work with the data.

The Cloud Links implementation leverages Oracle Cloud Infrastructure access mechanisms to make data accessible within a specific scope. Scope indicates who can remotely access the data. Scope can be set to various levels, including to the region where the database resides, to individual tenancies, or to compartments. In addition, you can specify that authorization to access a data set is limited to one or more Autonomous Database instances.

By creating one or more cross-region refreshable clones from the source (data set owner's) Autonomous Database instance, you can use Cloud Links to share data across multiple regions.

Cloud Links greatly simplify the sharing of tables or views across Autonomous Database instances, as compared to traditional database linking mechanisms. With Cloud Links you can discover data without requiring a complex database link setup. Autonomous Database provides transparent access using SQL, and implements privilege enforcement with the Cloud Links scope and by granting authorization to individual Autonomous Database instances.

Cloud Links introduce the concepts of regional namespaces and names for data that is made remotely accessible. This is similar to existing Oracle tables where there is a table, for example "EMP" that resides in a namespace (schema), for example "LWARD". There can only be one LWARD.EMP in your database. Cloud Links provide a similar namespace and name on a regional level, that is not tied to a single database but applies across many Autonomous Database instances as specified with the scope and optionally with database authorization.

For example, you can register a data set under the namespace FOREST and for security purposes or for naming convenience, you can provide a namespace and a name other than the original schema and object names. In this example, TREE_DATA is the visible name of the registered data set and this name is not required to be the name of the source table. In addition to the namespace and the name, the cloud$link keyword indicates to the database that it must resolve the source as a Cloud Link.

To access a registered data set, include the namespace, the name, and the cloud$link keyword in the FROM clause of a SELECT statement:

SELECT county, species, height FROM FOREST.TREE_DATA@cloud$link;

Optionally, you can specify that access to a data set from one or more databases is offloaded to a refreshable clone. When a consumer Autonomous Database is listed in a data set's offload list, access to the data set is directed to the refreshable clone.

There are several concepts and terms to use when you work with Cloud Links:

• Registered Data Set (Data Set): Identifies a table or view that has been enabled for remote access in an Autonomous Database. A registered data set also indicates who is allowed to access the data set (its scope). Data set registration defines a namespace and a name for use with Cloud Links. After data set registration, these values together specify the Fully Qualified Name (FQN) for remote access, and allow Cloud Links to manage accessibility for the data set.

• Data Set Owner: Specify a data set owner to provide a point of contact for questions about a data set.

• Scope: Specifies who and from where a user is allowed to access a registered data set. See Data Set Scope, Access Control, and Authorization for more details on scope.

• OCID (Oracle Cloud Identifier): Identifies a specific Tenancy, Compartment, or Database. The scope for a registered data set can be expressed in terms of OCIDs. See Resource Identifiers for more information.

• Data Registration: With data registration a user makes a table or view available for remote access, subject to the access restrictions imposed by scope, and optionally subject to an additional authorization step. You can allow remote access with Cloud Links on a table or view stored in the database or on data stored in Object Store.

• Data Discovery: A registered data set can be discovered using textual queries from the database. The discovery only shows a data set if there is a privilege to access the data set. You can search to find a registered data set by name or by description.

• Data Describe: Allows a user to retrieve a description or metadata for a table or view made available as a registered data set.

• Offload Targets: Optionally, you can specify one or more offload targets. Offload targets are refreshable clones that provide Cloud Links data sets to specified Autonomous Database instances. By specifying an offload target, you can dedicate an Autonomous Database instance to provide data sets to separate production from development, for performance, to assure security, or for other reasons. See Use Refreshable Clones with Autonomous Database for more information.

Any access to a registered data set using Cloud Links is logged for audit purposes. The log includes the tenancy, compartment, or database that accessed the data set, the amount of data accessed, and additional information. The V$CLOUD_LINK_ACCESS_STATS and GV$CLOUD_LINK_ACCESS_STATS Views show audit information.

• Data Set Scope, Access Control, and Authorization
  Cloud Links leverage Oracle Cloud Infrastructure access mechanisms to make registered data sets accessible, and to protect your data with access restrictions.

The ADMIN user grants privileges to database users to register data sets. The ADMIN user also grants privileges to database users to access registered data sets.

1. As the ADMIN user, allow a user to register data sets within a specified scope.

   BEGIN
   DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER(
      username => 'DB_USER1',
      scope    => 'MY$REGION');
   END;
   /

   This specifies that the user DB_USER1, has privileges to register data sets within a specified scope, 'MY$REGION'.

   A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') to check if they are enabled for registering data sets.

   For example, the following query:

   SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_REGISTER_ENABLED') FROM DUAL;

   Returns 'YES' or 'NO'.

   See GRANT_REGISTER Procedure for more information.

2. As the ADMIN user, allow a user to access registered data sets.

   EXEC DBMS_CLOUD_LINK_ADMIN.GRANT_READ('LWARD');

   This allows LWARD to access registered data sets that are available to the Autonomous Database instance.

   A user can query SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') to check if they are enabled for READ access to a data set.

   For example, the following query:

   SELECT SYS_CONTEXT('USERENV', 'CLOUD_LINK_READ_ENABLED') FROM DUAL;

   Returns 'YES' or 'NO'.

   See GRANT_READ Procedure for more information.

3. During data registration you can set the authorization required parameter to TRUE. When authorization required is TRUE, the ADMIN user must run DBMS_CLOUD_LINK_ADMIN.GRANT_AUTHORIZE to provide authorization to invoke DBMS_CLOUD_LINK.GRANT_AUTHORIZATION. Use DBMS_CLOUD_LINK.GRANT_AUTHORIZATION to specify authorization details.

   See Register a Data Set with Authorization Required for more information.

4. When the Autonomous Database instance has Database Vault enabled and the table or view to be registered with Cloud Links is protected by a realm, the owner of the table or view must be authorized to the realm as a realm-owner before registration.

   BEGIN
        DBMS_MACADM.ADD_AUTH_TO_REALM(
              realm_name   => 'myrealm',
              grantee      => 'object_owner',
              auth_option  => dbms_macutl.g_realm_auth_owner);
   END;
   /

   If the realm protecting the table or view is a mandatory realm, the Autonomous Database common schema named C##DATA$SHARE, which is used internally as the connecting schema, must be authorized to the realm as a realm-participant.

   For example:

   BEGIN
        DBMS_MACADM.ADD_AUTH_TO_REALM(
              realm_name   => 'myrealm',
              grantee      => 'C##DATA$SHARE',
              auth_option  => dbms_macutl.g_realm_auth_participant);
   END;
   /

   See Use Oracle Database Vault with Autonomous Database for more information.

You can register a table or view you own as a registered data set. When you want to remove or replace the data set, you need to unregister it.

1. Obtain grant register privileges from the ADMIN user.

   See Grant Cloud Links Access for Database Users for more information.

2. Register one ore more data sets.

   For example, assuming there is a schema CLOUDLINK on your Autonomous Database instance, you can register two objects, SALES_VIEW_AGG and SALES_ALL and provide different scope parameters to determine how the objects are accessed.

   BEGIN
      DBMS_CLOUD_LINK.REGISTER(
       schema_name    => 'CLOUDLINK',
       schema_object  => 'SALES_VIEW_AGG',
       namespace      => 'REGIONAL_SALES', 
       name           => 'SALES_AGG',
       description    => 'Aggregated regional sales information.',
       scope          => 'MY$TENANCY',
       auth_required  =>  FALSE,
       data_set_owner =>  'amit@example.com' );
   END;
   /

   BEGIN
      DBMS_CLOUD_LINK.REGISTER(
       schema_name    => 'CLOUDLINK',
       schema_object  => 'SALES_ALL',
       namespace      => 'TRUSTED_COMPARTMENT', 
       name           => 'SALES',
       description    => 'Trusted Compartment, only accessible within my compartment. Early sales data.',
       scope          => 'MY$COMPARTMENT',
       auth_required  =>  FALSE,
       data_set_owner =>  'amit@example.com' );
   END;
   /

   The parameters are:

   • schema_name: is the schema name (the object owner).

   • schema_object: is the object's name. Valid objects are:

     • Tables (including Heap, External or Hybrid)
     • Views
     • Materialized Views
     Note
     
     Other objects such as analytic views or synonyms are not supported.

   • namespace: is the namespace you provide as a name for access with Cloud Links (one part of the Cloud Link FQN).

     A NULL value specifies a system-generated namespace value, unique to the Autonomous Database instance.

   • name: is the name you provide for access with Cloud Links (one part of the Cloud Link FQN).

   • scope: Specifies the scope. You can use one of the variables: MY$REGION, MY$TENANCY, or MY$COMPARTMENT or specify one or more OCIDs.

     See Data Set Scope, Access Control, and Authorization for more information.

   • auth_required: A Boolean value that specifies if database level authorization is required for the data set, in addition to the scope access control. When this is set to TRUE, the data set enforces an additional authorization step. See Register a Data Set with Authorization Required for more information.

   • data_set_owner: Text value specifies information about the individual responsible for the data set or a contact for questions about the data set. For example, you could supply an email address for the data set owner.

   See REGISTER Procedure for more information.

   After the registration completes, the scope for these two registered objects are different, based on the scope parameter:

   • MY$TENANCY: Specifies tenancy level scope for REGIONAL_SALES.SALES_AGG.

   • MY$COMPARTMENT: Specifies the more restrictive compartment level scope for my compartment within my tenancy for TRUSTED_COMPARTMENT.SALES.

BEGIN
   DBMS_CLOUD_LINK.UNREGISTER(
    namespace      => 'TRUSTED_COMPARTMENT', 
    name           => 'SALES');
END;
/

• Notes for Registering or Unregistering a Data Set
  Provides notes for registering a data set with DBMS_CLOUD_LINK.REGISTER and unregistering a data set with DBMS_CLOUD_LINK.UNREGISTER.

You can use Cloud Links in multiple regions, where the source region contains the data set's source database and one or more remote regions contain refreshable clones of the source database.

To use Cloud Links with a data set in a different region:

1. Create a cross-region Refreshable Clone of the source database in a remote region.

   See Create a Cross Tenancy or Cross-Region Refreshable Clone for information on adding a cross-region refreshable clone.

2. On the source database, register the data set.

   See Register or Unregister a Data Set for more information.

3. Refresh the refreshable clone.

   See Refresh a Refreshable Clone on Autonomous Database for more information.

4. On the remote Refreshable Clone register the data set using the same arguments you used to register the data set in the source region.

   For example, assuming there is a schema CLOUDLINK on your Autonomous Database instance, after you the register SALES_ALL on the source database, register SALES_ALL on the refreshable clone:

   BEGIN
      DBMS_CLOUD_LINK.REGISTER(
       schema_name    => 'CLOUDLINK',
       schema_object  => 'SALES_ALL',
       namespace      => 'TRUSTED_COMPARTMENT', 
       name           => 'SALES',
       description    => 'Trusted Compartment, only accessible within my compartment. Early sales data.',
       scope          => 'MY$COMPARTMENT',
       auth_required  =>  FALSE,
       data_set_owner =>  'amit@example.com' );
   END;
   /

   The parameters are:

   • schema_name: is the schema name (the object owner).

   • schema_object: is the object's name. Valid objects are:

     • Tables (including Heap, External or Hybrid)
     • Views
     • Materialized Views
     Note
     
     Other objects such as analytic views or synonyms are not supported.

   • namespace: is the namespace you provide as a name for access with Cloud Links (one part of the Cloud Link FQN).

     A NULL value specifies a system-generated namespace value, unique to the Autonomous Database instance.

   • name: is the name you provide for access with Cloud Links (one part of the Cloud Link FQN).

   • scope: Specifies the scope. You can use one of the variables: MY$REGION, MY$TENANCY, or MY$COMPARTMENT or specify one or more OCIDs.

     See Data Set Scope, Access Control, and Authorization for more information.

   • auth_required: A Boolean value that specifies if database level authorization is required for the data set, in addition to the scope access control. When this is set to TRUE, the data set enforces an additional authorization step. See Register a Data Set with Authorization Required for more information.

   • data_set_owner: Text value specifies information about the individual responsible for the data set or a contact for questions about the data set. For example, you could supply an email address for the data set owner.

   See REGISTER Procedure for more information.

   After the registration completes on the refreshable clone, the scope for the registered object is MY$COMPARTMENT: Specifies the more restrictive compartment level scope for my compartment within my tenancy for TRUSTED_COMPARTMENT.SALES.

• Notes for Registering or Unregistering a Data Set in a Remote Region
  Provides notes for registering a data set in a remote region.

Optionally, when you register a data set, in addition to the scope you can specify that database level authorization is required to access a data set.

1. Use DBMS_CLOUD_LINK.REGISTER to register a data with authorization required.

   Assuming there is a schema CLOUDLINK on your Autonomous Database instance and you register the object SALES_VIEW_AGG and set auth_required to TRUE, then in addition to defining the scope, you must preform additional steps to determine how the object is accessed.

   BEGIN
      DBMS_CLOUD_LINK.REGISTER(
       schema_name    => 'CLOUDLINK',
       schema_object  => 'SALES_VIEW_AGG',
       namespace      => 'REGIONAL_SALES', 
       name           => 'SALES_AGG',
       description    => 'Aggregated regional sales information.',
       scope          => 'MY$TENANCY',
       auth_required  =>  TRUE,
       data_set_owner =>  'amit@example.com' );
   END;
   /

   The parameters are:

   • schema_name: is the schema name (the object owner).

   • schema_object: is the object's name. Valid objects are:

     • Tables (including Heap, External or Hybrid)
     • Views
     • Materialized Views
     Note
     
     Other objects such as analytic views or synonyms are not supported.

   • namespace: is the namespace you provide as a name for access with Cloud Links (one part of the Cloud Link FQN).

     A NULL value specifies a system-generated namespace value, unique to the Autonomous Database instance.

   • name: is the name you provide for access with Cloud Links (one part of the Cloud Link FQN).

   • scope: Specifies the scope. You can use one of the variables: MY$REGION, MY$TENANCY, or MY$COMPARTMENT or specify one or more OCIDs.

     See Data Set Scope, Access Control, and Authorization for more information.

   • auth_required: A Boolean value that specifies if database level authorization is required for the data set, in addition to the scope access control. When this is set to TRUE, the data set enforces an additional authorization step.

   • data_set_owner: Text value specifies information about the individual responsible for the data set or a contact for questions about the data set. For example, you could supply an email address for the data set owner.

2. Obtain the database ID for the database you want to grant authorization to (to allow the database to access to the data set).

   On the system you want to grant access the data set:

   SELECT DBMS_CLOUD_LINK.GET_DATABASE_ID FROM DUAL:

3. Use the database ID you obtained to grant authorization to a specified data set.

   You can only grant authorization, and run DBMS_CLOUD_LINK.GRANT_AUTHORIZATION, as shown in this step, if you are authorized. The ADMIN grants authorization with DBMS_CLOUD_LINK_ADMIN.GRANT_AUTHORIZE.

   BEGIN
      DBMS_CLOUD_LINK.GRANT_AUTHORIZATION(
       database_id    => '120xxxxxxx8506029999',
       namespace      => 'TRUSTED_COMPARTMENT', 
       name           => 'SALES');
   END;
   /

   Perform these steps multiple times if you want to authorize additional databases.

BEGIN
   DBMS_CLOUD_LINK.REVOKE_AUTHORIZATION(
    database_id    => '120xxxxxxx8506029999',
    namespace      => 'TRUSTED_COMPARTMENT', 
    name           => 'SALES');
END;
/

Optionally, when you register a data set you can offload access to the data set to one or more Autonomous Database instances that are refreshable clones.

Use the optional offload_targets parameter with DBMS_CLOUD_LINK.REGISTER to specify that access is offloaded to refreshable clones. The source database for each refreshable clone is the Autonomous Database instance where you register the data set (data publisher).

The offload_targets value is a JSON document that defines one or more CLOUD_LINK_DATABASE_ID and OFFLOAD_TARGET key value pairs:

• CLOUD_LINK_DATABASE_ID is one of:

  • A database ID: This specifies a database ID for the data set consumer whose request is offloaded to the corresponding refreshable clone specified with the OFFLOAD_TARGET value.

    Obtain the database ID by running DBMS_CLOUD_LINK.GET_DATABASE_ID. See GET_DATABASE_ID Function for more information.

  • ANY: This specifies that any data set consumer's request is offloaded to the corresponding offload target. A consumer's data set request will be routed to the corresponding offload target.

    If you specify ANY without specifying database IDs, all data set requests from consumers are offloaded to the refreshable clone specified with the OFFLOAD_TARGET value.

    If you specify both database IDs and ANY, data set requests from consumers that do not match a database ID are offloaded to the refreshable clone specified with the OFFLOAD_TARGET value.

• OFFLOAD_TARGET is the OCID for an Autonomous Database instance that is a refreshable clone.

The following figure illustrates using offload targets.

When a data set consumer requests access to a data set that you register with offload_targets and the Autonomous Database instance's database ID matches the value specified in CLOUD_LINK_DATABASE_ID, access is offloaded to the refreshable clone identified with OFFLOAD_TARGET in the supplied JSON.

For example, the following shows a JSON sample with three OFFLOAD_TARGET/CLOUD_LINK_DATABASE_ID value pairs:

{
  "OFFLOAD_TARGETS": [
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx69708978",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfabc"
    },
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx89898978",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdef"
    },
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx4755680",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfghi"
    }
  ]
}

When a data set consumer requests access to a data set that you register with offload_targets that includes the ANY keyword, access is offloaded to the refreshable clone identified with OFFLOAD_TARGET in the supplied JSON (except for requests from consumers that have a matching database ID entry in the supplied JSON).

For example, the following shows a JSON sample with one explicit OFFLOAD_TARGET/CLOUD_LINK_DATABASE_ID value pair, and one ANY value with a corresponding OFFLOAD_TARGET:

{
  "OFFLOAD_TARGETS": [
    {
      "CLOUD_LINK_DATABASE_ID": "ANY",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfdef"
    },
    {
      "CLOUD_LINK_DATABASE_ID": "34xxxxx4755680",
      "OFFLOAD_TARGET":
"ocid1.autonomousdatabase.oc1..xxxxx3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfghi"
    }
  ]
}

To register a data set and specify offload targets, do the following:

1. Obtain the OCID for one or more refreshable clones where you want to offload data set access. Refreshable clone OCIDs are available on the Oracle Cloud Infrastructure Console on a refreshable clone.
   Note
   
   It can take up to 10 minutes after you create a refreshable clone for the refreshable clone to be visible as an offload target. This means you may need to wait up to 10 minutes after you create a refreshable clone for the refreshable clone to be available for Cloud Links offload registration.
2. Obtain the database ID for one or more Autonomous Database instances that you want to access the data set using data provided by the refreshable clone.

   On the system you want to access the data set from a refreshable clone, run the command:

   SELECT DBMS_CLOUD_LINK.GET_DATABASE_ID FROM DUAL:

3. Register a data set and specify the offload_targets parameter.

   For example, assuming there is a schema CLOUDLINK on your Autonomous Database instance, you can register SALES_VIEW_AGG and specify the refreshable clones that provide access to the data set:

   BEGIN
      DBMS_CLOUD_LINK.REGISTER(
       schema_name     => 'CLOUDLINK',
       schema_object   => 'SALES_VIEW_AGG',
       namespace       => 'REGIONAL_SALES', 
       name            => 'SALES_AGG',
       description     => 'Aggregated regional sales information.',
       scope           => 'MY$TENANCY',
       auth_required   =>  FALSE,
       data_set_owner  =>  'amit@example.com',
       offload_targets => '{
     "OFFLOAD_TARGETS": [
       {
         "CLOUD_LINK_DATABASE_ID": "34xxxx754755680",
         "OFFLOAD_TARGET":
   "ocid1.autonomousdatabase.oc1..xxxxxaaba3pv6wkcr4jqae5f44n2b2m2yt2j6rx32uzr4h25vqstifsfghi"
       }
     ]
   }');
   END;
   /

   The parameters are:

   • schema_name: is the schema name (the object owner).

   • schema_object: is the object's name. Valid objects are:

     • Tables (including Heap, External or Hybrid)
     • Views
     • Materialized Views
     Note
     
     Other objects such as analytic views or synonyms are not supported.

   • namespace: is the namespace you provide as a name for access with Cloud Links (one part of the Cloud Link FQN).

     A NULL value specifies a system-generated namespace value, unique to the Autonomous Database instance.

   • name: is the name you provide for access with Cloud Links (one part of the Cloud Link FQN).

   • scope: Specifies the scope. You can use one of the variables: MY$REGION, MY$TENANCY, or MY$COMPARTMENT or specify one or more OCIDs.

     See Data Set Scope, Access Control, and Authorization for more information.

   • auth_required: A Boolean value that specifies if database level authorization is required for the data set, in addition to the scope access control. When this is set to TRUE, the data set enforces an additional authorization step. See Register a Data Set with Authorization Required for more information.

   • data_set_owner: Text value specifies information about the individual responsible for the data set or a contact for questions about the data set. For example, you could supply an email address for the data set owner.

   • offload_targets: Specifies one or more Autonomous Database OCIDs of refreshable clones where access to data sets is offloaded, from the Autonomous Database where the data set is registered.

     For each data set consumer, one of the following can match to offload the request to a refreshable clone:

     • When there is matching the value of the specified cloud_link_database_id, that is the values matches the consumer's database ID, access is offloaded to the refreshable clone identified by the OCID specified in offload_target.

     • When the ANY keyword is specified, if there is not a matching the value of a specified cloud_link_database_id, access is offloaded to the refreshable clone identified with the ANY entry by the OCID specified in the corresponding offload_target.

   See REGISTER Procedure for more information.

   See Use Refreshable Clones with Autonomous Database for more information.

You can share Cloud Links when a data set resides on a Read-Only Autonomous Database instance.

1. Change the database mode to Read/Write mode.
   See Change Autonomous Database Operation Mode to Read/Write Read-Only or Restricted for more information.
2. With the database in Read/Write mode, perform the steps to register a data set.
   1. Grant Cloud Links Access for Database Users
   2. Register or Unregister a Data Set
3. After you register one or more data sets, change the database to read-only mode.
   See Change Autonomous Database Operation Mode to Read/Write Read-Only or Restricted for more information.

A user who is granted access to read Cloud Links can search for data sets available to an Autonomous Database instance and can access and use registered data sets with their queries.

1. Find the available data sets on your Autonomous Database instance.

   For example, search for all data sets that contain the string, "TREE":

   DECLARE
      result CLOB DEFAULT NULL;
   BEGIN
      DBMS_CLOUD_LINK.FIND('TREE', result);
       DBMS_OUTPUT.PUT_LINE(result);
   END;
   /
   
   [{"name":"TREE_DATA","namespace":"FOREST","description":"Urban tree data including county, species and height"}]

   The parameters are:

   • search_string: The string to search for. The search string is not case sensitive.

   • search_result: A JSON document that includes the namespace, name, and description values for the data set.

   See FIND Procedure for more information.

   The DBMS_CLOUD_LINK.FIND procedure provides the FQN you can use with Cloud Links. In this case, FOREST.TREE_DATA.

2. Use the view DBA_CLOUD_LINK_ACCESS to list available data sets:

   SELECT * FROM DBA_CLOUD_LINK_ACCESS;
   
   NAMESPACE            NAME
   ---------            -------------- 
   FOREST               TREE_DATA 
   REGIONAL_SALES       SALES_AGG
   TRUSTED_COMPARTMENT  SALES

3. Use the procedure DBMS_CLOUD_LINK.DESCRIBE to find out more details about a registered data set.

   SELECT DBMS_CLOUD_LINK.DESCRIBE('FOREST','TREE_DATA') FROM DUAL;
   
   DBMS_CLOUD_LINK.DESCRIBE('FOREST','TREE_DATA')
   ---------------------------------------------------
   Urban tree data including county, species and height

4. Use the registered data set in a query.

   SELECT * FROM FOREST.TREE_DATA@cloud$link;

   Note
   
   It can take up to 10 minutes after you register a data set with DBMS_CLOUD_LINK.REGISTER for the data set to be visible and accessible.

The ADMIN user can revoke registration to disallow a user from registering data sets for remote access. The ADMIN user can also revoke privileges or database users to access registered data sets.

1. As the ADMIN user, revoke a user's privileges to register data sets.

   For example:

   EXEC DBMS_CLOUD_LINK_ADMIN.REVOKE_REGISTER('DB_USER1');

   This revokes the privileges to register data sets for the user, DB_USER1.

   Running DBMS_CLOUD_LINK_ADMIN.REVOKE_REGISTER does not affect data sets that are already registered. Use DBMS_CLOUD_LINK.UNREGISTER to remove access for a registered data set.

   See REVOKE_REGISTER Procedure and UNREGISTER Procedure for more information.

2. As the ADMIN user, revoke access to registered data sets.

   For example:

   EXEC DBMS_CLOUD_LINK_ADMIN.REVOKE_READ('LWARD');

   This revokes access to Cloud Links data sets for the user LWARD.

   See REVOKE_READ Procedure for more information.

Autonomous Database provides views that allow you to monitor and audit Cloud Links.

1. Obtain the unique Cloud Link database ID for the Autonomous Database instance where you want to provide full access.

   DECLARE
        DB_ID NUMBER;
    BEGIN
        DB_ID := DBMS_CLOUD_LINK.GET_DATABASE_ID;
        DBMS_OUTPUT.PUT_LINE('Database ID:' || DB_ID);
    END;
    /

2. Create VPD policy on the database that registered the data set by only allowing full access to the one specific database whose identifier you got on the database in question in Step 1.

   CREATE OR REPLACE FUNCTION vpd_policy_sales(
        owner IN VARCHAR2, 
        object IN VARCHAR2)
        RETURN VARCHAR2 IS
   BEGIN
     IF SYS_CONTEXT('USERENV', 'CLOUD_LINK_DATABASE_ID')  <> '12121212163948244901' THEN
       RETURN 'time_id >= trunc(sysdate,''year'')';  
     ELSE
       RETURN '';
     END IF;
   END;
   /

   See DBMS_RLS for more information.

3. Register the VPD policy for your registered data set to limit full access to only the database identified in step 1.

   
   BEGIN
     DBMS_RLS.ADD_POLICY(object_schema => 'CLOUDLINK',
               object_name => 'SALES_VIEW_AGG',
               policy_name => 'THIS_YEAR',
               function_schema => 'ADMIN',
               policy_function => 'VPD_POLICY_SALES',
               statement_types => 'SELECT',
               policy_type => DBMS_RLS.SHARED_CONTEXT_SENSITIVE);
   END;
   /

   See DBMS_RLS for more information.

Provides notes and restrictions for using Cloud Links.

• There is a limit of 4096 on the number of data sets you can register.

  Each Autonomous Database instance can register no more than 4096 data sets. This limit applies to every Autonomous Database instance, regardless of the number of ECPUs (OCPUs if your database uses OCPUs) or the storage size of the instance. The limit is a fixed value and setting the ECPU count to a larger value does not allow you to register more data sets.

• You can register an object in another schema if you have READ WITH GRANT OPTION privilege on the object.

• To register data sets or see and access remote data sets, you have to have granted the appropriate privilege for either registering or reading data sets. This is true for ADMIN as well; however ADMIN can grant this privilege to themself.

• To use DBMS_CLOUD_LINK.REGISTER, you must have execute privilege on the DBMS_CLOUD_LINK package, in addition to the register privilege assigned with DBMS_CLOUD_LINK_ADMIN.GRANT_REGISTER. Only the ADMIN user and schemas with PDB_DBA have this privilege by default.

• If you drop and re-create a table that was registered, you need to re-register the table for remote access.

• Only the ADMIN user and users with the role PDB_DBA are privileged to access the following views:

  • DBA_CLOUD_LINK_ACCESS

  • DBA_CLOUD_LINK_REGISTRATIONS

  • DBA_CLOUD_LINK_AUTHORIZATIONS

  • DBA_CLOUD_LINK_PRIVS

  See DBMS_CLOUD_LINK Views for more information.

• Accessing registered, remote data requires the remote database to be open. If the remote database is closed or in restricted mode, you will not be able to access the data and an Oracle error will be returned.

• There is a limit of a maximum of four open database links per session. Exceeding this limit can lead to ORA-02020 or ORA-12545.

• If result cache is enabled, like the default behavior in Autonomous Database with Data Warehouse workload, you need to ensure that result cache is not used when realtime data is required.

• When you update your license type from Free to Paid, you must re-register Cloud Links data sets. See Update Always Free Instance to Paid with Autonomous Database for more information.

• Cloud Links remote connectivity uses the LOW service and this cannot be changed. You can see the remote connections as user C##DATA$SHARE in V$SESSION and the Cloud Links views V$CLOUD_LINK_ACCESS_STATS and GV$CLOUD_LINK_ACCESS_STATS Views provide more details about remote connections.

• All interfaces are case-sensitive unless otherwise noted, as follows:

  • Anything you enter that exists in the database, for example user names and table names, case is significant and must be entered with uppercase letters.
  • Predefined variables, for example the predefined scope values must be entered in uppercase letters.
  • Anything that you specify for the setup of Cloud Links, for example namespaces or names of tables in a namespace, must be specified as entered. For example, if you define a namespace as trees, you must enclose the namespace in double quotes, as "trees", when accessing it with SQL.

• You can share Cloud Links when a data set resides on an Autonomous Database instance in Read-Only mode. See Use Cloud Links from a Read Only Autonomous Database Instance for more information.

• It can take up to 10 minutes after you create a refreshable clone for the refreshable clone to be visible as an offload target. This means you may need to wait up to 10 minutes after you create a refreshable clone for the refreshable clone to be available for Cloud Links offload registration.

  See Register a Data Set with Offload Targets for Data Set Access and Create a Refreshable Clone for an Autonomous Database Instance for more information.