Resumen de subprogramas DBMS_DCAT
En esta tabla se muestran los procedimientos de paquete DBMS_DCAT utilizados para crear, consultar y borrar conexiones de Data Catalog.
| Subprograma | Descripción |
|---|---|
| Procedimiento SET_DATA_CATALOG_CREDENTIAL | Definir la credencial de acceso al catálogo de datos utilizada por una conexión específica al catálogo de datos |
| Procedimiento SET_OBJECT_STORE_CREDENTIAL | Definir la credencial utilizada por el identificador de conexión único proporcionado para acceder al almacén de objetos |
| Procedimiento SET_DATA_CATALOG_CONN | Crear una conexión al catálogo de datos proporcionado |
| Procedimiento UNSET_DATA_CATALOG_CONN | Eliminar una conexión de Data Catalog existente |
Procedimiento SET_DATA_CATALOG_CREDENTIAL
Este procedimiento define la credencial de acceso a Data Catalog que utiliza una conexión específica a Data Catalog.
Sintaxis
PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(
credential_name VARCHAR2(128) DEFAULT NULL,
dcat_con_id VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
credential_name |
Credencial utilizada para acceder a Data Catalog. |
dcat_con_id |
Identificador de conexión único de Data Catalog. Esta credencial se utiliza para la conexión identificada por dcat_con_id. El valor por defecto es Null. |
Esta credencial debe tener permisos de gestión de Data Catalog; consulte Políticas de Data Catalog.
Procedimiento SET_OBJECT_STORE_CREDENTIAL
Este procedimiento define la credencial que utiliza el identificador de conexión único proporcionado para acceder al almacén de objetos. El cambio de la credencial de acceso al almacén de objetos modifica todas las tablas sincronizadas existentes para utilizar la nueva credencial.
Sintaxis
PROCEDURE DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(
credential_name VARCHAR2(128),
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
credential_name |
Credencial utilizada por las tablas externas para acceder al almacén de objetos. |
dcat_con_id |
Identificador de conexión único de Data Catalog. El valor por defecto es NULL. |
Procedimiento SET_DATA_CATALOG_CONN
Este procedimiento crea una conexión al catálogo de datos proporcionado. Se necesita la conexión para sincronizar los metadatos con Data Catalog. Una instancia de base de datos de IA autónoma puede conectarse a varias instancias de Data Catalog y admite la conexión a OCI Data Catalogs y AWS Glue Data Catalogs.
Sintaxis
PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CONN (
region VARCHAR2 DEFAULT NULL,
endpoint VARCHAR2 DEFAULT NULL,
catalog_id VARCHAR2 DEFAULT NULL,
dcat_con_id VARCHAR2 DEFAULT NULL,
catalog_type VARCHAR2 DEFAULT NULL,
token_endpoint VARCHAR2 DEFAULT Null
);
Parámetros
| parámetro | Descripción |
|---|---|
region |
Región de Data Catalog. Si se especifica endpoint, region es opcional. Si se proporcionan endpoint y region, endpoint tiene prioridad. El valor por defecto es NULL. |
endpoint |
Punto final de Data Catalog. Si se especifica region, endpoint es opcional. Si se proporcionan endpoint y region, endpoint tiene prioridad. El valor por defecto es NULL. |
catalog_id |
Identificador único de Oracle Cloud (OCID) para la instancia de Data Catalog. Al conectarse a los catálogos de datos de AWS Glue, catalog_id es opcional. |
dcat_con_id |
Identificador de conexión único de Data Catalog. Este identificador es necesario al conectarse a varios catálogos de datos y es opcional al conectarse solo a uno. Se utiliza para hacer referencia a la conexión de Data Catalog en llamadas posteriores o al consultar vistas. Si no se especifica ningún identificador, este procedimiento genera un identificador de conexión NULL. La siguiente restricción se aplica a dcat_con_id:
|
catalog_type |
Tipo de catálogo de datos que se va a conectar. Valores permitidos:
|
token_endpoint |
Punto final de token de acceso para la autenticación de OAuth. El valor por defecto es NULL. |
Uso
Solo necesita llamar a este procedimiento una vez para establecer la conexión. Como parte del proceso de conexión, Autonomous AI Database agrega propiedades personalizadas a Data Catalog. Los usuarios de Data Catalog pueden acceder a estas propiedades personalizadas y permiten sustituir nombres por defecto (para esquemas, tablas y columnas) y tipos de dato de columna.
Antes de crear una conexión, se deben crear y definir credenciales. Para obtener una descripción del proceso de conexión, consulte Flujo de trabajo típico con Data Catalog para OCI Data Catalogs y Flujo de trabajo de usuario para consultas con AWS Glue Data Catalog para AWS Glue Data Catalogs.
Ejemplos
Ejemplo: conexión con un OCID conocido
En este ejemplo, la base de datos de IA autónoma se conecta a Data Catalog en la región uk-london-1. El parámetro catalog_id utiliza el identificador de Oracle Cloud (ocid) para la instancia de Data Catalog. El tipo de Data Catalog se determina automáticamente: AWS Glue Data Catalog o OCI Data Catalog.
BEGIN
DBMS_DCAT.SET_DATA_CATALOG_CONN(
region=>'uk-london-1',
catalog_id=>'ocid1.datacatalog.oc1.uk-london-1...');
END;
/
Ejemplo: conexión a un catálogo de datos de AWS Glue
Una conexión es la asociación entre una instancia de base de datos de IA autónoma y un catálogo de datos de AWS Glue. Después de una conexión correcta, la instancia de base de datos de IA autónoma puede sincronizarse con AWS Glue. Cada cuenta de AWS tiene un catálogo de datos de AWS Glue por región y se puede acceder a cada catálogo mediante el punto final de servicio correspondiente para cada región. Una instancia de base de datos de IA autónoma se puede asociar a un catálogo de datos de AWS Glue llamando a la API DBMS_DCAT.SET_DATA_CATALOG_CONN y especificando el punto final de la región en la que reside el catálogo.
Consulte Puntos finales y cuotas de AWS Glue.
En este ejemplo, la base de datos de IA autónoma se conecta a un catálogo de datos de AWS Glue en la región uk-london-1. Debido a que se trata de una conexión de AWS Glue Data Catalog, el parámetro catalog_id no es necesario.
BEGIN
DBMS_DCAT.SET_DATA_CATALOG_CONN(
region=>'uk-london-1',
catalog_type=>'AWS_GLUE'
END;
/
Procedimiento UNSET_DATA_CATALOG_CONN
Este procedimiento elimina una conexión existente a Data Catalog.
Sintaxis
Nota: Al llamar a este procedimiento se borran todos los esquemas protegidos y las tablas externas que se han creado como parte de las sincronizaciones anteriores. No afecta a los metadatos de Data Catalog.
PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
dcat_con_id |
Identificador de conexión único de Data Catalog. El valor por defecto es Null. |
Subprogramas de sincronización
La ejecución de una sincronización, la creación y el borrado de un trabajo de sincronización y el borrado de esquemas sincronizados se pueden realizar con los procedimientos que se muestran en esta tabla.
Nota: El 4 de abril de 2022, se agregaron los parámetros sync_option y grant_read al procedimiento DBMS_DCAT.RUN_SYNC. Para garantizar un rendimiento correcto de los trabajos de sincronización programados creados antes de esa fecha, debe borrar y volver a crear los trabajos de sincronización programados. Consulte Procedimiento DROP_SYNC_JOB y Procedimiento CREATE_SYNC_JOB.
| Subprograma | Descripción |
|---|---|
| Procedimiento CREATE_SYNC_JOB | Crear un trabajo del programador para llamar a RUN_SYNC periódicamente |
| Procedimiento DROP_SYNC_JOB | Borrar un trabajo de sincronización existente para el identificador de conexión único proporcionado |
| Procedimiento DROP_SYNCED_SCHEMAS | Borrar todos los esquemas sincronizados previamente para el identificador de conexión único proporcionado |
| Procedimiento RUN_SYNC | Ejecutar una operación de sincronización |
Procedimiento RUN_SYNC
Este procedimiento ejecuta una operación de sincronización y es el punto de entrada de la sincronización. Como entrada, toma listas de activos, carpetas y entidades de Data Catalog seleccionados y los materializa mediante la creación, el borrado y la modificación de tablas externas.
El parámetro sync_option especifica la operación que realiza el procedimiento RUN_SYNC: SYNC, DELETE o REPLACE. La operación se realiza en entidades dentro del ámbito del parámetro synced_objects.
Cada llamada al procedimiento RUN_SYNC devuelve un único operation_id que se puede utilizar para consultar la vista USER_LOAD_OPERATIONS para obtener información sobre el estado de la sincronización y el log_table correspondiente. Se puede consultar la vista DBMS_DCAT$SYNC_LOG para acceder fácilmente a log_table para la última operación de sincronización ejecutada por el usuario actual. Para obtener más información, consulte la vista DBMS_DCAT$SYNC_LOG.
Nota: El 4 de abril de 2022, se agregaron los parámetros sync_option y grant_read al procedimiento DBMS_DCAT.RUN_SYNC. Para garantizar un rendimiento correcto de los trabajos de sincronización programados creados antes de esa fecha, debe borrar y volver a crear los trabajos de sincronización programados. Consulte Procedimiento DROP_SYNC_JOB y Procedimiento CREATE_SYNC_JOB.
Sincronización de Entidades Lógicas Particionadas o Tablas de Pegado
El procedimiento RUN_SYNC crea una tabla externa particionada para cada entidad lógica o tabla Glue cuando se aplican las tres de las siguientes opciones:
-
La entidad lógica del catálogo de datos de OCI o la tabla Glue tienen uno o más atributos particionados.
-
Para los catálogos de datos de OCI, la entidad lógica se deriva de un patrón de nombre de archivo basado en prefijos. Las entidades lógicas particionadas derivadas de patrones basados en expresiones regulares no están soportadas.
-
Para los catálogos de datos de OCI, la entidad lógica se basa en datos particionados que siguen el formato de carpeta de tipo colmena o no colmada. Las entidades lógicas basadas en datos particionados que siguen el formato de estilo no dinámico utilizando nombres de objeto no están soportadas.
-
Ejemplo 1. Entidades lógicas basadas en objetos recopilados que siguen el formato de partición de estilo de Hive con patrones de nombre de archivo basados en prefijos.
Considere los siguientes objetos:
Bucket: MYBUCKET cluster1/db1.db/sales/country=USA/year=2020/month=01/sales1.csv cluster1/db1.db/sales/country=USA/year=2020/month=01/sales2.csv cluster1/db1.db/sales/country=USA/year=2020/month=02/sales1.csvAl recopilar el cubo mediante un patrón de nombre de archivo con un prefijo de carpeta inicial
cluster1/db1.db, se genera una entidad lógica denominadaSALEScon tres atributos de partición:country,yearymonth. El tipo de los atributos particionados esPartitionmientras que el tipo de los atributos no particionados esPrimitive. -
Ejemplo 2. Entidades lógicas basadas en objetos recopilados que siguen el formato de partición de estilo no Hive con patrones de nombre de archivo basados en prefijos.
Considere los siguientes objetos:
Bucket: MYBUCKET cluster2/db2.db/sales/USA/2020/01/sales1.csv cluster2/db2.db/sales/USA/2020/01/sales2.csv cluster2/db2.db/sales/USA/2020/02/sales1.csvAl recopilar el cubo mediante un patrón de nombre de archivo con un prefijo de carpeta inicial
cluster2/db2.db, se genera una entidad lógica denominadaSALEScon tres atributos de partición:name0, name1 yname2. La única diferencia entre la entidad lógica generada en comparación con el Ejemplo 1 es que los nombres de los atributos particionados se generan automáticamente, mientras que en el Ejemplo 1 se extraen de la URL (country,yearymonthrespectivamente).
-
Para obtener un ejemplo completo de extremo a extremo de la sincronización de entidades lógicas particionadas, consulte Ejemplo: escenario de datos particionados.
Sincronización Incremental de Entidades Lógicas Particionadas/Tablas de Valores
Cada llamada al procedimiento RUN_SYNC especifica un juego de entidades lógicas del catálogo de datos de OCI o tablas de AWS Glue que se sincronizarán con la base de datos. Cuando una entidad lógica o tabla de pegado está presente en dos llamadas RUN_SYNC, la segunda llamada conserva y posiblemente altera las tablas externas existentes. La siguiente tabla muestra qué cambios de entidad lógica o tabla de pegado están soportados cuando se particiona la entidad lógica o la tabla de pegado:
| Cambio de entidad lógica o tabla de pegado | Acción |
|---|---|
| Adición, eliminación o actualización de una partición | Todas las particiones de la tabla particionada externa se actualizan, independientemente de si el catálogo de datos ha detectado un cambio. |
| Adición de un atributo particionado | No está soportada la adición de una columna particionada a una tabla particionada externa. Se ha emitido una excepción. |
| Supresión de un atributo de partición | No está soportado borrar una columna particionada de una tabla particionada externa. Se ha emitido una excepción. |
| Cambio de Nombre de un Atributo Particionado | No se admite el cambio de nombre de una columna particionada en una tabla particionada externa. Se ha emitido una excepción. |
Sintaxis
PROCEDURE DBMS_DCAT.RUN_SYNC (
synced_objects IN CLOB,
sync_option IN VARCHAR2 DEFAULT 'SYNC',
error_semantics IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
log_level IN VARCHAR2 DEFAULT 'INFO',
grant_read IN VARCHAR2 DEFAULT NULL,
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
PROCEDURE DBMS_DCAT.RUN_SYNC (
synced_objects IN CLOB,
sync_option IN VARCHAR2 DEFAULT 'SYNC',
error_semantics IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
log_level IN VARCHAR2 DEFAULT 'INFO',
grant_read IN VARCHAR2 DEFAULT NULL,
operation_id OUT NOCOPY NUMBER,
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
synced_objects |
Este parámetro es un documento JSON que especifica los objetos del catálogo de datos que sincronizar. Para OCI Data Catalogs, el documento JSON especifica un juego de entidades con varias granularidades: activos de datos, carpetas (cubos del almacén de objetos) o entidades lógicas. Contiene una Para los catálogos de datos de AWS Glue, el documento JSON especifica una lista de tablas con granularidad múltiple: bases de datos, tablas. El documento especifica una lista de bases de datos. Los usuarios pueden restringir el juego de tablas que se van a sincronizar especificando tablas individuales en una base de datos. |
sync_option |
(Opcional) Hay tres opciones:
|
error_semantics |
(Opcional) Este parámetro especifica el comportamiento del error. Si se define en SKIP_ERRORS, la sincronización intenta continuar a pesar de los errores encontrados para entidades individuales. Si se define en STOP_ON_ERROR, el procedimiento falla en el primer error encontrado. El valor por defecto es SKIP_ERRORS. |
log_level |
(Opcional) Este parámetro especifica los siguientes valores para aumentar el nivel de detalle de registro: (OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL). El valor por defecto es INFO. |
grant_read |
(Opcional) Este parámetro es una lista de usuarios/roles a los que se otorgan automáticamente privilegios READ en todas las tablas externas procesadas por esta llamada de RUN_SYNC. A todos los usuarios/roles de la lista grant_read se les otorgan privilegios de lectura en todas las tablas externas nuevas o ya existentes que corresponden a entidades especificadas por el parámetro synced_objects. El procedimiento RUN_SYNC conserva los privilegios ya otorgados en las tablas externas sincronizadas. |
operation_id |
(Opcional) Este parámetro se utiliza para buscar la entrada correspondiente en Nota: Hay disponible una versión de |
dcat_con_id |
Este parámetro es el identificador de conexión único del catálogo de datos que se especificó cuando se creó la conexión al catálogo de datos. Consulte Procedimiento SET_DATA_CATALOG_CONN. Este parámetro identifica qué conexión se utiliza para la sincronización y se convierte en parte del nombre de esquema derivado. Consulte Asignación de Sincronización para obtener una descripción de cómo se deriva el nombre del esquema. El parámetro por defecto es NULL. |
Ejemplos
Ejemplo: sincronización de todas las entidades de OCI Data Catalog.
En el siguiente ejemplo, se sincronizan todas las entidades de Data Catalog.
EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');
Ejemplo: parámetro synced_objects para sincronizar todos los activos de datos de OCI Data Catalog.
A continuación se muestra un parámetro synced_objects de ejemplo para sincronizar todos los activos de datos (Object Storage) en Data Catalog.
{"asset_list" : ["*"]}
Ejemplo: parámetro synced_objects para sincronizar activos de datos específicos de OCI Data Catalog.
A continuación se muestra un parámetro synced_objects de ejemplo para sincronizar dos activos de datos.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f"
},
{
"asset_id":"...-9e2e7f74523"
}
]}
Ejemplo: parámetro synced_objects para sincronizar entidades específicas de OCI Data Catalog en un activo de datos.
A continuación, se muestra un parámetro synced_objects de ejemplo para sincronizar dos entidades en el activo de datos.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f",
"folder_list":[
"f1",
"f2"
]
}
]}
Ejemplo: parámetro synced_objects para sincronizar entidades y carpetas específicas de OCI Data Catalog dentro de un activo de datos.
A continuación, se muestra un parámetro synced_objects de ejemplo para sincronizar dos carpetas y dos entidades dentro del activo de datos.
{"asset_list":[
{
"asset_id":"...-9e2e7f78fd5f",
"entity_list": [
"entity1",
"entity2"
],
"folder_list": [
"f1",
"f2"
]
}
]}
Ejemplo: parámetro synced_objects para sincronizar todas las bases de datos del catálogo de datos de AWS Glue.
A continuación, se muestra un parámetro synced_objects de ejemplo para sincronizar todas las bases de datos en el catálogo de datos de AWS Glue.
{"database_list":["*"]}
Ejemplo: parámetro synced_objects para sincronizar dos bases de datos del catálogo de datos de AWS Glue.
A continuación, se muestra un parámetro synced_objects de ejemplo para sincronizar dos bases de datos de AWS Glue Data Catalog.
{"database_list":[
{"database":"tpcdscsv"},
{"database":"tpcdsparquet"} ]}
Ejemplo: parámetro synced_objects para sincronizar tres bases de datos del catálogo de datos de AWS Glue.
A continuación, se muestra un parámetro synced_objects de ejemplo para sincronizar tres tablas desde una base de datos de AWS Glue Data Catalog.
{"database_list":[
{"database":"tpcdsparquet",
"table_list": [ "tpcdsparquet_customer",
"tpcdsparquet_item",
"tpcdsparquet_web_sales" ] } ]}
Procedimiento CREATE_SYNC_JOB
Este procedimiento crea un trabajo del programador para llamar a RUN_SYNC periódicamente
Toma como entrada el juego de objetos que se va a sincronizar, la semántica de error, el nivel de log y un intervalo de repetición. Consulte Procedimiento RUN_SYNC para obtener más información sobre cómo funciona la sincronización.
Solo puede haber un único trabajo de sincronización. El procedimiento CREATE_SYNC_JOB falla si ya se ha especificado otro trabajo, a menos que el parámetro force se defina en TRUE. Si force se define en TRUE, se borra el trabajo anterior.
Si un trabajo del programador intenta ejecutarse mientras hay otra sincronización en curso, el trabajo del programador falla.
Nota: El 4 de abril de 2022, se agregaron los parámetros sync_option y grant_read al procedimiento DBMS_DCAT.RUN_SYNC. Para garantizar un rendimiento correcto de los trabajos de sincronización programados creados antes de esa fecha, debe borrar y volver a crear los trabajos de sincronización programados. Consulte Procedimiento DROP_SYNC_JOB y Procedimiento CREATE_SYNC_JOB.
Sintaxis
PROCEDURE DBMS_DCAT.CREATE_SYNC_JOB (
synced_objects IN CLOB,
error_semantics IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
log_level IN VARCHAR2 DEFAULT 'INFO',
repeat_interval IN VARCHAR2,
force IN VARCHAR2 DEFAULT 'FALSE',
grant_read IN VARCHAR2 DEFAULT NULL,
sync_option IN VARCHAR2 DEFAULT 'SYNC',
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
synced_objects |
Un objeto JSON que especifica los objetos que se van a sincronizar, como se describe en el procedimiento RUN_SYNC. Consulte Procedimiento RUN_SYNC. |
error_semantics |
(Opcional) Comportamiento de error, según se especifica para RUN_SYNC. El valor por defecto es SKIP_ERRORS. |
log_level |
(Opcional) Nivel de registro, según se especifica para RUN_SYNC. El valor por defecto es INFO. |
repeat_interval |
Repita el intervalo para el trabajo, con la misma semántica que el parámetro de intervalo de repetición del procedimiento DBMS_SCHEDULER.CREATE_JOB. Para obtener más información sobre repeat_interval, consulte Visión general de la creación de trabajos. |
force |
(Opcional) Si es TRUE, los trabajos de sincronización existentes se suprimen primero. Si FALSE, el procedimiento CREATE_SYNC_JOB falla si ya existe un trabajo de sincronización. El valor por defecto es FALSE. |
grant_read |
(Opcional) Lista de usuarios/roles a los que se debe otorgar lectura en las tablas externas sincronizadas, como se describe para el procedimiento RUN_SYNC. Consulte Procedimiento RUN_SYNC. |
sync_option |
(Opcional) Comportamiento con respecto a las entidades que ya se han sincronizado mediante una operación RUN_SYNC anterior, como se describe para el procedimiento RUN_SYNC. Consulte Procedimiento RUN_SYNC. |
dcat_con_id |
Este parámetro es el identificador de conexión único de Data Catalog que se especificó cuando se creó la conexión a Data Catalog. Consulte Procedimiento SET_DATA_CATALOG_CONN. Este parámetro identifica qué conexión se utiliza para la sincronización y se convierte en parte del nombre de esquema derivado. Consulte Asignación de Sincronización para obtener una descripción de cómo se deriva el nombre del esquema. El parámetro por defecto es NULL. |
Procedimiento DROP_SYNC_JOB
Este procedimiento borra un trabajo de sincronización existente para el identificador de conexión único proporcionado.
Sintaxis
PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
dcat_con_id |
Identificador de conexión único de Data Catalog. El valor por defecto es NULL. |
Procedimiento DROP_SYNCED_SCHEMAS
Este procedimiento borra todos los esquemas sincronizados previamente para el identificador de conexión único proporcionado.
Sintaxis
PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parámetros
| parámetro | Descripción |
|---|---|
dcat_con_id |
Identificador de conexión único de Data Catalog. El valor por defecto es NULL. |