Catalog Functions

The Oracle Data Studio Catalog or Catalog is a multi-catalog tool that provides a way to search for data and other objects in your currently connected Autonomous Database, and also in a wide range of other connected systems.

The Catalog API functionality enables to browse, search and discovering connected data assets from anywhere in the cloud and beyond.

It also enables to mount new catalogs over other systems and search for data and other items in the connected Autonomous Database.

The Catalog API functionality enables to mount new catalogs over:
  • Other Autonomous Databases in your tenancy.
  • Any other database that can be connected using a DB Link, for example an on-premises database that your Autonomous Database can connect to.
  • Shared data, for example data shared from DataBricks using Delta Sharing.
  • Existing external data Catalogs such as AWS Glue, or the OCI Data Catalog.

This below section provides functions examples to help you get started using the Oracle Data Studio Catalog API.

Before using these examples, you must create the ADP instance and then connect.
import adp as ords
adp = ords.login('<protocol://host:port>', 'schema_name', 'schema_password')
Catalog = adp.Catalog

Get Catalogs Procedure

This function receives list of catalogs.

Syntax

Catalog.get_catalogs(search)
Parameters:
  • search (String): It is user supplied catalog search text. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value None for it.

Return Type

It is JSON String

Return Structure
'[

{"label": catalog name (String),

"type": catalog type (String),

"id": catalog id (String),

"details" : catalog details (JSON Nested Object),

"enabled": catalog enabled status (true | false),

"created": catalog create date (String)

"updated": catalog update date (String)},

 ...

]'
Example
import json
import pandas as pd
# catalog api function call
r = Catalog.get_catalogs()
# pandas data frame representation
j = json.loads(r)
pd.json_normalize(j)


Description of get_catalogs.png follows
Description of the illustration get_catalogs.png

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message
    (String)}'

Get Catalog Entities Procedure

This function receives list of catalog entities.

Syntax

Catalog.get_catalog_entities(catalog_name, type, search)
Parameters:
  • catalog_name (String): It is a user supplied catalog name.
  • type (String): It is a user supplied catalog entity type. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value TABLE for it.
  • catalog entity types : 'TABLE', 'VIEW', 'SCHEMA', etc.
  • search (String): It is user supplied catalog search text.
Examples
import json
import pandas as pd

# catalog api function call
r = Catalog.get_catalog_entities('CATALOG_DELTA_SHARING_1')

# pandas data frame representation
j = json.loads(r)
pd.json_normalize(j)


Description of get_catalog_entities.png follows
Description of the illustration get_catalog_entities.png

Return Type

It is JSON String.

Return Structure
'[

{"label": catalog entity name (String),

"type": catalog entity type (String),

"schema": catalog schema (String),

"id": catalog entity id (String).

"details" : catalog entity details (JSON Nested Object),

"created": catalog entity create date (String)

"updated": catalog entity update date (String)},

...

]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Get Database Links Procedure

This function receives list of catalog entities.

Syntax

Catalog.get_database_links(catalog_name, owner, search)
Parameters:
  • catalog_name (String): It is a user supplied catalog name.
  • owner (String): It is user supplied catalog owner name.
  • search (String): It is user supplied catalog search text. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value NONE for it.

Return Type

It is JSON String.

Return Structure
'[

{"label":  data base link name (String),

"type": database link type (String),

"catalog": data base link catalog (String),

"application": data base link application (String).

"credentialName": data base link credential name (String),

"credentialOwner": data base link credential owner (String),

"hidden": data base link is hidden (String),

"valid": data base link is valid (String),

"created": database link created create date (String)

"updated": database link created update date (String),

]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Get Autonomous Database Procedure

This function receives Oracle Data Studio Catalog autonomous databases.

Syntax

Catalog.get_autonomous_database(search)
Parameters:
  • search (String): It is user supplied catalog search text. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value NONE for it.

Return Type

It is JSON String.

Return Structure
'[

{"label": autonomous database name (String),

"type": autonomous database type (String),

"catalog": autonomous database catalog (String),

"application": autonomous database application (String).

"schema": autonomous database schema (String),

"workloadType": autonomous database workload type (String),

"lifecycleState": autonomous database life cycle state (String),

"ocid": autonomous database ocid (String),

"created":  autonomous database create date (String)

"updated":  autonomous database update date (String),
]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Enable Catalog Procedure

This function enables Oracle Data Studio Catalog.

Syntax

Catalog.enable_catalog(catalog_name)
Parameters:
  • catalog_name (String): It is a user supplied catalog name.
Example
# catalog api function call
Catalog.enable_catalog('CATALOG_DELTA_SHARING_1')
Output
'{ "updated": true }'

Return Type

It is JSON String.

Return Structure
'{ "updated": operation status (True | False)}'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Disable Catalog Procedure

This function disables Oracle Data Studio Catalog.

Syntax

Catalog.enable_catalog(catalog_name)
Parameters:
  • catalog_name (String): It is a user supplied catalog name.
Examples
# catalog api function call
Catalog.disable_catalog('CATALOG_DELTA_SHARING_1')

Output

'{ "updated": true }'

Return Type

It is JSON String.

Return Structure
'{ "updated": operation status (True | False)}'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Unmount Catalog Procedure

This function disables Oracle Data Studio Catalog.

Syntax

Catalog.unmount_catalog(catalog_name)
Parameters:
  • catalog_name (String): It is a user supplied catalog name.
Example
# catalog api function call
Catalog.unmount_catalog('CATALOG_DELTA_SHARING_1')
Output
'{ "unmounted": true }'

Return Type

It is JSON String.

Return Structure
'{ "unmounted": operation status (true | false)}'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Preview Catalog Table Procedure

This function previews Oracle Data Studio Catalog table.

Syntax

Catalog.preview_catalog_table(catalog_name, table_name, schema_name,
    row_limit)
Parameters:
  • catalog_name (String): It specifies catalog name.
  • table_name (String): It specifies catalog table name.
  • schema_name (String): It specifies catalog schema name.
  • row_limit (Number): It specifies catalog table preview row limit. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value 100 for it.
Example
import pandas as pd

# catalog api function call
q = Catalog.preview_catalog_table(
                           catalog_name = 'CATALOG_DELTA_SHARING_1', 
                           table_name   = 'COVID_19_NYT',                                       
                           schema_name  = 'DEFAULT')

# pandas data frame representation
pd.DataFrame.from_records(q)

Output


Description of preview-catalog.png follows
Description of the illustration preview-catalog.png

Return Type

It is JSON String.

Return Structure
'[{"columnName": "row_value",.. }, {}, ...]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Mount OCI Data Catalog Procedure

This function mounts OCI Data Catalog.

Syntax

Catalog.mount_oci_data_catalog(catalog_name, oci_catalog_credential, oci_catalog_region, oci_catalog_name, oci_storage_credential)
Parameters:
  • catalog_name (String): It specifies catalog name.
  • oci_catalog_credential (String): It specifies OCI catalog credential.
  • oci_catalog_region (String): It specifies OCI catalog region.
  • oci_catalog_name (String): It specifies OCI catalog name.
  • oci_storage_credential (String): It specifies OCI storage credential. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value None for it.

Return Type

It is JSON String.

Return Structure
'[{"catalogName": catalog name (String),
   "shareName": share name (String)}]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Mount Autonomous Database Share Catalog Procedure

This function mounts autonomous database share Catalog.

Syntax

Catalog.mount_autonomous_database_catalog(catalog_name, database_name, create_database_link,
      database_link_name, credential_name)
Parameters:
  • catalog_name (String): It specifies catalog name.
  • database_name (String): It specifies autonomous database name.
  • create_database_link (Boolean): It creates database link name mode. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value False for it.
  • database_link_name (String): It is a database link name. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value False for it.
  • credential_name (String): It is a swift credential name. This parameter is not required to be provided by the user when making a request, and if it is omitted, the system will automatically use the default value False for it.

Return Type

It is JSON String.

Return Structure
'[{"catalogName": catalog name (String),
   "shareName": share name (String)}]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'

Mount Shares Catalog Procedure

This function mounts Oracle Data Studio Shares Catalog.

Syntax

Catalog.mount_shares_catalog(catalog_name, share_name,
    share_provider)
Parameters:
  • catalog_name (String): It specifies catalog name.
  • share_name (String): It is a share name.
  • share_provider (String): It is share provider name.
Example
Mount Shares Catalog# catalog api function call
Catalog.mount_shares_catalog (
        catalog_name   = 'CATALOG_DELTA_SHARING_1',
        share_name     = 'DELTA_SHARING',
        share_provider = 'PROVIDER_DELTA_SHARING_1')
Output
'[{"catalogName":"CATALOG_DELTA_SHARING_1","shareName":"DELTA_SHARING"}]'

Return Type

It is JSON String.

Return Structure
'[{"catalogName": catalog name (String),
"shareName": share name (String)}]'

Error Type

JSON String

Error Structure

'{"code": error code (Number), "error": error message (String)}'