DBMS_CLOUD pour les objets et les fichiers

Cette section traite des sous-programmes DBMS_CLOUD utilisés pour utiliser des objets et des fichiers.

Prérequis

En tant que développeur, vous pouvez utiliser les procédures DBMS_CLOUD avec des bases de données d'IA autonomes déployées sur Oracle Public Cloud, Multicloud ou Exadata Cloud@Customer.

Selon le choix de déploiement, les prérequis suivants doivent être respectés pour utiliser les procédures DBMS_CLOUD avec les fournisseurs de services Amazon S3, Azure Blob Storage et Google Cloud Storage.

DBMS_CLOUD pour les objets et les fichiers

Les sous-programmes de gestion des objets et des fichiers dans le package DBMS_CLOUD.

Sous-programme Description
Procédure COPY_COLLECTION Cette procédure charge les données dans une collection SODA existante à partir du stockage d'objets cloud ou à partir de fichiers d'un répertoire.
Procédure COPY_DATA Cette procédure charge les données dans les tables de base de données Autonomous AI existantes à partir du stockage d'objets cloud ou des fichiers d'un répertoire.
Procédure COPY_DATA pour les fichiers Avro, ORC ou Parquet

Cette procédure avec le paramètre format type défini sur la valeur orc, parquet ou avro charge les données dans les tables de base de données Autonomous AI existantes à partir de fichiers ORC, Parquet ou Avro dans le cloud ou à partir de fichiers ORC, Parquet ou Avro dans un répertoire.

Comme pour les fichiers texte, les données sont copiées à partir du fichier ORC, Parquet ou Avro source dans la table interne préexistante.
Procédure COPY_OBJECT Cette procédure copie les fichiers d'un bucket Cloud Object Storage vers un autre.
Procédure CREATE_EXTERNAL_TABLE Cette procédure crée une table externe sur les fichiers dans le cloud ou sur les fichiers dans un répertoire. Vous pouvez ainsi exécuter des requêtes sur des données externes à partir d'une base de données Autonomous AI.
Procédure CREATE_EXTERNAL_TABLE pour les fichiers Avro, ORC ou Parquet

Cette procédure, avec le paramètre format type défini sur la valeur parquet,orc ou avro, crée une table externe avec des fichiers au format Parquet, ORC ou Avro dans le cloud ou dans un répertoire.

Vous pouvez ainsi exécuter des requêtes sur des données externes à partir d'une base de données Autonomous AI.
Procédure CREATE_EXTERNAL_TEXT_INDEX Cette procédure crée un index de texte sur les fichiers de banque d'objets.
Procédure CREATE_HYBRID_PART_TABLE Cette procédure crée une table partitionnée hybride. Vous pouvez ainsi exécuter des requêtes sur des données partitionnées hybrides à partir d'une base de données Autonomous AI.
Procédure DELETE_ALL_OPERATIONS Cette procédure efface toutes les opérations de chargement de données consignées dans la table user_load_operations de votre schéma, ou toutes les opérations de chargement de données du type spécifié, comme indiqué dans le paramètre type.
Procédure DELETE_FILE Cette procédure enlève le fichier spécifié du répertoire indiqué sur la base de données Autonomous AI
Procédure DELETE_OBJECT Cette procédure supprime l'objet spécifié de la banque d'objets.
Procédure DELETE_OPERATION Cette procédure accepte une entrée operation_id et supprime les journaux associés à l'entrée operation_id indiquée.
Procédure DROP_EXTERNAL_TEXT_INDEX Cette procédure supprime l'index de texte dans les fichiers de la banque d'objets.
Procédure EXPORT_DATA Cette procédure exporte les données d'une base de données Autonomous AI vers des fichiers dans le cloud en fonction du résultat d'une requête. La forme surchargée permet d'utiliser le paramètre operation_id. En fonction de l'option type du paramètre format indiquée, la procédure exporte les lignes vers la banque d'objets cloud sous forme de texte avec les options CSV, JSON, Parquet ou XML
Procédure et fonction GET_OBJECT Cette procédure est surchargée. Cette procédure lit un objet à partir du stockage d'objet cloud et le copier vers la base de données Autonomous AI. Le formulaire de fonction lit un objet à partir du stockage d'objet cloud et renvoie une valeur BLOB vers la base de données Autonomous AI.
Fonction LIST_FILES Cette fonction liste les fichiers présents dans le répertoire spécifié. Les résultats incluent les noms de fichier et les métadonnées supplémentaires sur les fichiers, telles que la taille de fichier en octets, l'horodatage de création et l'horodatage de dernière modification.
Fonction LIST_OBJECTS Cette fonction répertorie les objets présents à l'emplacement spécifié dans la banque d'objets. Les résultats incluent les noms d'objet et les métadonnées supplémentaires sur les objets, telles que la taille, le checksum, l'horodatage de création et l'horodatage de dernière modification.
Procédure MOVE_OBJECT Cette procédure déplace un objet d'un bucket Cloud Object Storage vers un autre.
Procédure PUT_OBJECT Cette procédure est surchargée. Dans un formulaire, la procédure copie un fichier d'Autonomous AI Database vers Cloud Object Storage. Dans un autre formulaire, la procédure copie une valeur BLOB d'Autonomous AI Database vers Cloud Object Storage.
Procédure SYNC_EXTERNAL_PART_TABLE Cette procédure simplifie la mise à jour d'une table partitionnée externe à partir de fichiers dans le cloud. Exécutez cette procédure chaque fois que de nouvelles partitions sont ajoutées ou lorsque des partitions sont supprimées de la source de la banque d'objets pour la table partitionnée externe.
Procédure VALIDATE_EXTERNAL_TABLE Cette procédure valide les fichiers source pour une table externe, génère une information sur le journal et stocke les lignes qui ne correspondent pas aux options de format indiquées pour la table externe dans une table badfile sur Autonomous AI Database.
Procédure VALIDATE_EXTERNAL_PART_TABLE Cette procédure valide les fichiers source pour une table partitionnée externe, génère une information sur le journal et stocke les lignes qui ne correspondent pas aux options de format indiquées pour la table externe dans une table badfile sur Autonomous AI Database,
Procédure VALIDATE_HYBRID_PART_TABLE Cette procédure valide les fichiers source pour la table partitionnée hybride, génère les informations de journal et stocke les lignes qui ne correspondent pas aux options de format indiquées pour la table hybride dans une table badfile sur la base de données Autonomous AI.

Procédure COPY_COLLECTION

Cette procédure charge les données dans une collection SODA à partir du stockage d'objet cloud ou d'un répertoire. Si la collection SODA spécifiée n'existe pas, la procédure la crée. La forme surchargée permet d'utiliser le paramètre operation_id.

Syntaxe

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL
);
DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL,
    operation_id      OUT NOCOPY NUMBER
);

Paramètres

Paramètre Description
collection_name Nom de la collection SODA dans laquelle les données sont chargées. Si une collection portant ce nom existe déjà, les données spécifiées sont chargées, sinon, la collection est créée.
credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Ce paramètre n'est pas utilisé lorsque vous indiquez un répertoire avec file_uri_list.

file_uri_list

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

URI de fichier source cloud

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Exemple :

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

Répertoire

Vous pouvez indiquer un répertoire et un ou plusieurs noms de fichier ou utiliser une liste de répertoires et de noms de fichier séparés par des virgules. Le format pour spécifier un répertoire est :'MY_DIR:filename.ext'. Par défaut, le nom de répertoire MY_DIR est un objet de base de données et ne tient pas compte de la casse. Ce nom de fichier distingue les majuscules des minuscules.

Vous pouvez utiliser des caractères génériques pour indiquer des noms de fichier dans un répertoire. Le caractère "*" peut être utilisé comme caractère générique pour représenter plusieurs caractères. Le caractère "?" peut être utilisé comme caractère générique pour représenter un seul caractère. Par exemple :'MY_DIR:*" ou 'MY_DIR:test?'

Pour spécifier plusieurs répertoires, utilisez une liste de répertoires séparés par des virgules : par exemple :'MY_DIR1:*, MY_DIR2:test?'

Utilisez des guillemets doubles pour indiquer un nom de répertoire sensible à la casse. Par exemple :'"my_dir1":*, "my_dir2":Test?'

Pour inclure un guillemet, utilisez deux guillemets. Par exemple :'MY_DIR:''filename.ext'. Cela indique que filename commence par un guillemet (').

format

Options décrivant le format des fichiers source. Ces options sont indiquées sous forme de chaîne JSON.

Les formats pris en charge sont : characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray, keyassignment et keypath.

Outre les formats mentionnés pour les données JSON, Autonomous AI Database prend aussi en charge d'autres formats. Pour obtenir la liste des arguments de format pris en charge par Autonomous AI Database, reportez-vous à Paramètre de format.

operation_id Utilisez ce paramètre pour suivre la progression et le statut final de l'opération de chargement sous l'ID correspondant dans la vue USER_LOAD_OPERATIONS.

Exemple

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );

    DBMS_CLOUD.COPY_COLLECTION(
            collection_name => 'myCollection',
            credential_name => 'OBJ_STORE_CRED',
            file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/myCollection.json'
            );
END;
/

Procédure COPY_DATA

Cette procédure charge les données dans les tables de base de données Autonomous AI existantes à partir de fichiers dans le cloud ou de fichiers dans un répertoire. La forme surchargée permet d'utiliser le paramètre operation_id.

Syntaxe

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2,
    field_list        IN CLOB,
    format            IN CLOB);
DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB DEFAULT NULL,
    schema_name       IN VARCHAR2 DEFAULT NULL,
    field_list        IN CLOB DEFAULT NULL,
    format            IN CLOB DEFAULT NULL
    operation_id      OUT NOCOPY NUMBER);

Paramètres

Paramètre Description
table_name Nom de la table cible dans la base de données. Vous devez avoir créé la table cible avant d'exécuter COPY_DATA.
credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Ce paramètre n'est pas utilisé lorsque vous indiquez un répertoire avec file_uri_list.

file_uri_list

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

URI de fichier source cloud

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Exemple :

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

Répertoire

Vous pouvez indiquer un répertoire et un ou plusieurs noms de fichier ou utiliser une liste de répertoires et de noms de fichier séparés par des virgules. Le format pour spécifier un répertoire est :'MY_DIR:filename.ext'. Par défaut, le nom de répertoire MY_DIR est un objet de base de données et ne tient pas compte de la casse. Ce nom de fichier distingue les majuscules des minuscules.

Vous pouvez utiliser des caractères génériques pour indiquer des noms de fichier dans un répertoire. Le caractère "*" peut être utilisé comme caractère générique pour représenter plusieurs caractères. Le caractère "?" peut être utilisé comme caractère générique pour représenter un seul caractère. Par exemple :'MY_DIR:*" ou 'MY_DIR:test?'

Pour spécifier plusieurs répertoires, utilisez une liste de répertoires séparés par des virgules : par exemple :'MY_DIR1:*, MY_DIR2:test?'

Utilisez des guillemets doubles pour indiquer un nom de répertoire sensible à la casse. Par exemple :'"my_dir1":*, "my_dir2":Test?'

Pour inclure un guillemet, utilisez deux guillemets. Par exemple :'MY_DIR:''filename.ext'. Cela indique que filename commence par un guillemet (').

schema_name Nom du schéma dans lequel réside la table cible. La valeur par défaut est NULL, ce qui signifie que la table cible se trouve dans le même schéma que l'utilisateur qui exécute la procédure.
field_list

Identifie les champs dans les fichiers source et leurs types de données. La valeur par défaut est NULL, ce qui signifie que les champs et leur type de données sont déterminés par le paramètre column_list. La syntaxe de cet argument est identique à la clause field_list dans les tables externes Oracle standard. Pour plus d'informations, reportez-vous à field_list dans Utilitaires Oracle Database 19c ou Utilitaires Oracle Database 26ai.

Lorsque la valeur de l'option type du paramètre format est json, ce paramètre est ignoré.

Pour obtenir un exemple d'utilisation de field_list, reportez-vous à Procédure CREATE_EXTERNAL_TABLE.

format

Options décrivant le format des fichiers source, des fichiers journaux et des fichiers incorrects. Pour obtenir la liste des options et découvrir comment spécifier les valeurs, reportez-vous à Paramètre de format.

Pour connaître les options de format de fichier Avro, ORC ou Parquet, reportez-vous à Options de format de package DBMS_CLOUD pour Avro, ORC ou Parquet.

operation_id Utilisez ce paramètre pour suivre la progression et le statut final de l'opération de chargement sous l'ID correspondant dans la vue USER_LOAD_OPERATIONS.

Remarque sur l'utilisation

Le délimiteur d'enregistrement par défaut est detected newline. Avec detected newline, DBMS_CLOUD tente de trouver automatiquement le caractère de nouvelle ligne correct à utiliser comme délimiteur d'enregistrement. DBMS_CLOUD recherche d'abord le caractère de retour à la ligne Windows \r\n. S'il trouve le caractère à la ligne Windows, celui-ci est utilisé comme délimiteur d'enregistrement pour tous les fichiers de la procédure. If a Windows newline character is not found, DBMS_CLOUD searches for the UNIX/Linux newline character \n, and if it finds one it uses \n as the record delimiter for all files in the procedure. Si les fichiers source utilisent une combinaison de différents délimiteurs d'enregistrement, vous risquez de rencontrer une erreur telle que "KUP-04020: found record longer than buffer size supported". Dans ce cas, vous devez soit modifier les fichiers source pour utiliser le même délimiteur d'enregistrement, soit spécifier uniquement les fichiers source qui utilisent le même délimiteur d'enregistrement.

Pour plus d'informations sur l'option de format recorddelmiter, reportez-vous à Paramètre de format.

Exemples 

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );
END;
/
BEGIN
 DBMS_CLOUD.COPY_DATA(
    table_name =>'CHANNELS',
    credential_name =>'DEF_CRED_NAME',
    file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt',
    format => json_object('delimiter' value ',')
 );
END;
/
BEGIN
    DBMS_CLOUD.COPY_DATA(
            table_name      => 'ORDERS',
            schema_name     => 'TEST_SCHEMA',
            credential_name => 'DEF_CRED_NAME',
	     file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/orde[r]s.tbl.1'
            format          =>  json_object('ignoreblanklines' value TRUE,
                                            'rejectlimit' value '0',
                                            'dateformat' value 'yyyy-mm-dd',
                                            'regexuri' value TRUE)
            );
END;
/

Procédure COPY_DATA pour les fichiers Avro, ORC ou Parquet

Cette procédure avec le paramètre format type défini sur la valeur avro, orc ou parquet charge les données dans les tables de base de données Autonomous AI existantes à partir des fichiers Avro, ORC ou Parquet dans le cloud ou à partir des fichiers d'un répertoire.

Comme pour les fichiers texte, les données sont copiées à partir du fichier Avro, ORC ou Parquet source dans la table interne préexistante.

Syntaxe

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    schema_name       IN VARCHAR2 DEFAULT,
    field_list        IN CLOB DEFAULT,
    format            IN CLOB DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table cible dans la base de données. Vous devez avoir créé la table cible avant d'exécuter COPY_DATA.
credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Ce paramètre n'est pas utilisé lorsque vous indiquez un répertoire avec file_uri_list.

file_uri_list

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

URI de fichier source cloud

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Exemple :

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

Répertoire

Vous pouvez indiquer un répertoire et un ou plusieurs noms de fichier ou utiliser une liste de répertoires et de noms de fichier séparés par des virgules. Le format pour spécifier un répertoire est :'MY_DIR:filename.ext'. Par défaut, le nom de répertoire MY_DIR est un objet de base de données et ne tient pas compte de la casse. Ce nom de fichier distingue les majuscules des minuscules.

Vous pouvez utiliser des caractères génériques pour indiquer des noms de fichier dans un répertoire. Le caractère "*" peut être utilisé comme caractère générique pour représenter plusieurs caractères. Le caractère "?" peut être utilisé comme caractère générique pour représenter un seul caractère. Par exemple :'MY_DIR:*" ou 'MY_DIR:test?'

Pour spécifier plusieurs répertoires, utilisez une liste de répertoires séparés par des virgules : par exemple :'MY_DIR1:*, MY_DIR2:test?'

Utilisez des guillemets doubles pour indiquer un nom de répertoire sensible à la casse. Par exemple :'"my_dir1":*, "my_dir2":Test?'

Pour inclure un guillemet, utilisez deux guillemets. Par exemple :'MY_DIR:''filename.ext'. Cela indique que filename commence par un guillemet (').

schema_name Nom du schéma dans lequel réside la table cible. La valeur par défaut est NULL, ce qui signifie que la table cible se trouve dans le même schéma que l'utilisateur qui exécute la procédure.
field_list

Ignoré pour les fichiers Avro, ORC ou Parquet.

Les champs de la source correspondent aux colonnes de la table externe par nom. Les types de données source sont convertis en types de données de colonne de table externe.

For ORC files, see DBMS_CLOUD Package ORC to Oracle Data Type Mapping.

Pour les fichiers Parquet, reportez-vous à la section DBMS_CLOUD Package Parquet to Oracle Data Type Mapping pour plus de détails sur le mapping.

Pour les fichiers Avro, reportez-vous à la section DBMS_CLOUD Package Avro to Oracle Data Type Mapping pour plus de détails sur le mapping.

format Options décrivant le format des fichiers source. Pour les fichiers Avro, ORC ou Parquet, seules deux options sont prises en charge : reportez-vous à Options de format de package DBMS_CLOUD pour Avro, ORC ou Parquet.

Remarques sur l'utilisation

Procédure COPY_OBJECT

Cette procédure copie un objet d'un bucket ou dossier Cloud Object Storage vers un autre.

Le dossier ou le bucket source et cible peuvent se trouver dans le même fournisseur de banque d'objets cloud ou dans un autre fournisseur.

Lorsque la source et la cible se trouvent dans des banques d'objets distinctes ou ont des comptes différents avec le même fournisseur cloud, vous pouvez donner des noms d'informations d'identification distincts pour les emplacements source et cible.

Par défaut, le nom des informations d'identification source est également utilisé par l'emplacement cible lorsque le nom des informations d'identification cible n'est pas fourni.

Syntaxe

DBMS_CLOUD.COPY_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

Paramètres

Paramètre Description
source_credential_name

Nom des infos d'identification permettant d'accéder au stockage d'objet cloud source.

Si vous ne fournissez pas de valeur source_credential_name, credential_name est défini sur NULL.

source_object_uri

Spécifie l'URI, qui pointe vers l'emplacement du dossier ou du bucket Object Storage source.

Ce paramètre est obligatoire.

Le format des URI dépend du service Cloud Object Storage. Pour plus d'informations, reportez-vous à Formats d'URI de stockage d'objet cloud.

target_object_uri

Indique l'URI de la banque d'objets cible.

Ce paramètre est obligatoire.

Le format des URI dépend du service Cloud Object Storage. Pour plus d'informations, reportez-vous à Formats d'URI de stockage d'objet cloud.

target_credential_name

Nom des données d'identification permettant d'accéder à l'emplacement de stockage d'objet cloud cible.

Si vous ne fournissez pas de valeur target_credential_name, target_object_uri est défini sur la valeur source_credential_name.

Exemple

BEGIN
DBMS_CLOUD.COPY_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

Procédure CREATE_EXTERNAL_PART_TABLE

Cette procédure crée une table partitionnée externe sur les fichiers dans le cloud ou à partir de fichiers dans un répertoire. Vous pouvez ainsi exécuter des requêtes sur des données externes à partir d'une base de données Autonomous AI.

Syntaxe

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);


DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    file_uri_list        IN VARCHAR2,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table externe.
credential_name Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.
partitioning_clause

Spécifie la clause de partitionnement complète, y compris les informations d'emplacement pour les partitions individuelles.

Si vous utilisez le paramètre partitioning_clause, le paramètre file_uri_list n'est pas autorisé.

file_uri_list

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

URI de fichier source cloud

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Cette option est uniquement prise en charge avec les tables externes créées sur un fichier dans Object Storage.

Exemple :

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Si vous utilisez le paramètre file_uri_list, le paramètre partitioning_clause n'est pas autorisé.

Le format des URI dépend du service Cloud Object Storage. Pour plus d'informations, reportez-vous à Formats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

column_list

Liste des noms et des types de données de colonne pour la table externe, séparés par des virgules. Ce paramètre présente les exigences suivantes, en fonction du type de fichier de données indiqué avec le paramètre file_uri_list :

  • Le paramètre column_list est requis avec les fichiers non structurés. A l'aide de fichiers non structurés, par exemple avec des fichiers texte CSV, le paramètre column_list doit spécifier tous les noms et types de données de colonne dans le fichier de données, ainsi que les colonnes de partition dérivées du nom d'objet.

  • Le paramètre column_list est facultatif avec les fichiers structurés. Par exemple, avec les fichiers de données Avro, ORC ou Parquet, column_list n'est pas requis. Lorsque l'élément column_list n'est pas inclus, l'option partition_columns du paramètre format doit inclure des spécifications pour les noms de colonne (name) et les types de données (type).

field_list Identifie les champs dans les fichiers source et leurs types de données. La valeur par défaut est NULL, ce qui signifie que les champs et leur type de données sont déterminés par le paramètre column_list. La syntaxe de cet argument est identique à la clause field_list dans les tables externes Oracle standard. Pour plus d'informations, reportez-vous à field_list dans Utilitaires Oracle Database 19c ou Utilitaires Oracle Database 26ai.
format

L'option de format partition_columns indique les noms de colonne DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE et les types de données des colonnes de partition lorsque les colonnes de partition sont dérivées du chemin de fichier, selon le type de fichier de données, structuré ou non structuré :

  • Lorsque le paramètre DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE inclut le paramètre column_list et que les fichiers de données ne sont pas structurés, par exemple avec des fichiers texte CSV, partition_columns n'inclut pas le type de données. Par exemple, utilisez un format tel que le suivant pour ce type de spécification partition_columns : 

    '"partition_columns":["state","zipcode"]'

    Le type de données n'est pas requis car il est indiqué dans le paramètre DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE column_list.

  • Lorsque DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE n'inclut pas le paramètre column_list et que les fichiers de données sont structurés, tels que les fichiers Avro, ORC ou Parquet, l'option partition_columns inclut à la fois le nom de colonne, la sous-clause name et le type de données, la sous-clause type. Par exemple, l'exemple suivant présente une spécification partition_columns : 

    '"partition_columns":[ {"name":"country", "type":"varchar2(10)"}, {"name":"year", "type":"number"}, {"name":"month", "type":"varchar2(10)"}]'

Si les fichiers de données ne sont pas structurés et que la sous-clause type est indiquée avec partition_columns, la sous-clause type est ignorée.

Pour les noms d'objet qui ne sont pas basés sur le format de ruche, l'ordre des colonnes indiquées par partition_columns doit correspondre à l'ordre dans lequel elles apparaissent dans le nom d'objet dans le chemin de fichier indiqué dans le paramètre file_uri_list.

Pour afficher toutes les options de paramètre format décrivant le format des fichiers source, reportez-vous à Formats d'URI Cloud Object Storage.

Remarques sur l'utilisation

Exemples 

Exemple : utilisation du paramètre partitioning_clause.

BEGIN
   DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
      table_name =>'PET1',
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) location
                                    ( ''&base_URL//file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000) location
                                    ( ''&base_URL/file_31.txt'')
                                 )'
     );
   END;
/


BEGIN
    DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
       table_name          => 'PET',
       format              => json_object('delimiter'value ','),
       column_list         => 'name varchar2(20), gender varchar2(10), salary number',
       partitioning_clause => 'partition by range (salary)
              (   -- Use test1.csv in the DEFAULT DIRECTORY DATA_PUMP_DIR
                  partition p1 values less than (100) LOCATION (''test1.csv''),
                   -- Use test2.csv in a specified directory MY_DIR
                  partition p2 values less than (300) DEFAULT DIRECTORY MY_DIR LOCATION (''test2.csv'')        )'   );
END;
/

Exemple : utilisation des paramètres file_uri_list et column_list avec des fichiers de données non structurés.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
   table_name => 'MYSALES',
   credential_name => 'DEF_CRED_NAME',
   file_uri_list     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.csv',
   column_list       => 'product varchar2(100), units number, country varchar2(100), year number, month varchar2(2)',
   field_list        => 'product, units', --[Because country, year and month are not in the file, they are not listed in the field list]
   format            => '{"type":"csv", "partition_columns":["country","year","month"]}');
END;
/

Exemple : utilisation de file_uri_list sans le paramètre column_list avec des fichiers de données structurées.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
  table_name => 'MYSALES',
  credential_name => 'DEF_CRED_NAME',
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
    table_name      => 'MYSALES',
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.parquet',
    format          =>
        json_object('type' value 'parquet', 'schema' value 'first',
                    'partition_columns' value
                          json_array(
                                json_object('name' value 'country', 'type' value 'varchar2(100)'),
                                json_object('name' value 'year', 'type' value 'number'),
                                json_object('name' value 'month', 'type' value 'varchar2(2)')
                          )
         )
    );
END;
/

Exemple : création de tables partitionnées externes à l'aide des objets stockés dans le bucket C3 Object Storage.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
     table_name => 'USAGE_EXTP',
     credential_name => 'OBJECT_STORAGE_CREDENTIAL',
     file_uri_list => 'https://objectstorage.mydomain.com/n/mytenancy/b/mybucket/o/usage-data/*usage-data*.parquet',
     format => json_object(
          'type' value 'parquet', 'schema' value 'first',
          'partition_columns' value json_array(
                json_object('name' value 'year', 'type' value 'number'),         
                json_object('name' value 'month', 'type' value 'number'),
                json_object('name' value 'day', 'type' value 'number')
          )
     )
   );
END;
/

Procédure CREATE_EXTERNAL_TABLE

Cette procédure crée une table externe sur les fichiers dans le cloud ou à partir de fichiers dans un répertoire. Vous pouvez ainsi exécuter des requêtes sur des données externes à partir d'une base de données Autonomous AI.

Syntaxe

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table externe.
credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Ce paramètre n'est pas utilisé lorsque vous indiquez un répertoire ou une URL de lien hypertexte de table avec file_uri_list.

file_uri_list

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

URI de fichier source cloud

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Cette option est uniquement prise en charge avec les tables externes créées sur un fichier dans Object Storage.

Exemple :

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

Annuaire

Vous pouvez indiquer un répertoire et un ou plusieurs noms de fichier ou utiliser une liste de répertoires et de noms de fichier séparés par des virgules. Le format pour spécifier un répertoire est :'MY_DIR:filename.ext'. Par défaut, le nom de répertoire MY_DIR est un objet de base de données et ne tient pas compte de la casse. Ce nom de fichier distingue les majuscules des minuscules.

Vous pouvez utiliser des caractères génériques pour indiquer des noms de fichier dans un répertoire. Le caractère "*" peut être utilisé comme caractère générique pour représenter plusieurs caractères. Le caractère "?" peut être utilisé comme caractère générique pour représenter un seul caractère. Par exemple :'MY_DIR:*" ou 'MY_DIR:test?'

Pour spécifier plusieurs répertoires, utilisez une liste de répertoires séparés par des virgules : par exemple :'MY_DIR1:*, MY_DIR2:test?'

Utilisez des guillemets doubles pour indiquer un nom de répertoire sensible à la casse. Par exemple :'"my_dir1":*, "my_dir2":Test?'

Pour inclure un guillemet, utilisez deux guillemets. Par exemple :'MY_DIR:''filename.ext'. Cela indique que filename commence par un guillemet (').

column_list Liste des noms et des types de données de colonne pour la table externe, séparés par des virgules.
field_list Identifie les champs dans les fichiers source et leurs types de données. La valeur par défaut est NULL, ce qui signifie que les champs et leurs types De données sont déterminés par le paramètre column_list. La syntaxe de cet argument est identique à la clause field_list dans les tables externes Oracle Database standard. Pour plus d'informations sur field_list, reportez-vous à ORACLE_LOADER Access Driver field_list sous field_definitions Clause dans Oracle Database 19c Utilities ou Oracle Database 26ai Utilities.
format

Options décrivant le format des fichiers source. Pour obtenir la liste des options et découvrir comment spécifier les valeurs, reportez-vous à Paramètre de format.

Pour les fichiers au format Avro, ORC ou Parquet, reportez-vous à Procédure CREATE_EXTERNAL_TABLE pour les fichiers Avro, ORC ou Parquet.

Remarques sur l'utilisation

Exemples 

Exemple : création d'une table externe à partir d'un fichier CSV dans Object Storage.

BEGIN
   DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
      table_name =>'WEATHER_REPORT_DOUBLE_DATE',
      credential_name =>'OBJ_STORE_CRED',
      file_uri_list =>'&base_URL/Charlotte_NC_Weather_History_Double_Dates.csv',
      format => json_object('type' value 'csv', 'skipheaders' value '1'),
      field_list => 'REPORT_DATE DATE''mm/dd/yy'',
                     REPORT_DATE_COPY DATE ''yyyy-mm-dd'',
                     ACTUAL_MEAN_TEMP,
                     ACTUAL_MIN_TEMP,
                     ACTUAL_MAX_TEMP,
                     AVERAGE_MIN_TEMP,
                     AVERAGE_MAX_TEMP,
                     AVERAGE_PRECIPITATION',
      column_list => 'REPORT_DATE DATE,
                     REPORT_DATE_COPY DATE,
                     ACTUAL_MEAN_TEMP NUMBER,
                     ACTUAL_MIN_TEMP NUMBER,
                     ACTUAL_MAX_TEMP NUMBER,
                     AVERAGE_MIN_TEMP NUMBER,
                     AVERAGE_MAX_TEMP NUMBER,
                     AVERAGE_PRECIPITATION NUMBER');
   END;
/

SELECT * FROM WEATHER_REPORT_DOUBLE_DATE where
   actual_mean_temp > 69 and actual_mean_temp < 74

Exemple : création d'une table externe à l'aide des objets stockés dans le bucket C3 Object Storage.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
     table_name =>'CHANNELS_EXT',
     credential_name =>'OBJECT_STORAGE_CREDENTIAL',
     file_uri_list => '<https://objectstorage.mydomain.com/n/mytenancy/b/mybucket/o/channels.txt>',
     format => json_object('delimiter' value ','),
     column_list => 'CHANNEL_ID NUMBER, CHANNEL_DESC VARCHAR2(20), CHANNEL_CLASS VARCHAR2(20)'
  );
END;
/

Procédure CREATE_EXTERNAL_TABLE pour Apache Iceberg

Cette procédure crée des tables externes pour les tables Apache Iceberg dans les configurations prises en charge.

Ces configurations spécifiques sont prises en charge :

Syntaxe

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB DEFAULT NULL,
    field_list       IN CLOB DEFAULT NULL,
    format           IN CLOB DEFAULT NULL
);

Paramètres

Paramètre Description
table_name Nom de la table externe.
credential_name

Nom des informations d'identification utilisées pour accéder aux fichiers de données, aux fichiers de métadonnées et au catalogue Iceberg (le cas échéant).

Pour les configurations AWS et OCI, les informations d'identification doivent être créées comme décrit dans la procédure CREATE_CREDENTIAL.

Les informations d'identification AWS Amazon Resource Names (ARN) ne sont actuellement pas prises en charge.
file_uri_list Doit avoir la valeur NULL si un catalogue Iceberg est spécifié (voir le paramètre format ci-dessous). Si aucun catalogue d'iceberg n'est utilisé, le fichier file_uri_list doit contenir l'URI du fichier de métadonnées d'iceberg.
column_list

Doit être NULL car les noms et les types de colonne sont automatiquement dérivés des métadonnées Iceberg.

Les noms de colonne correspondent aux noms trouvés dans les fichiers de données sous-jacents (Parquet, Avro, ORC). Les types de données Oracle sont dérivés à l'aide des mappings Parquet/Avro/ORC entre Iceberg et les types de données Parquet, Avro et ORC. Par conséquent, les utilisateurs ne peuvent pas spécifier column_list.

field_list Doit être NULL car les noms de colonne et les types de données sont automatiquement dérivés des métadonnées Iceberg.
format

Le paramètre format a une structure différente selon le type de table Iceberg et les informations utilisées pour créer la table externe, par exemple les informations d'un catalogue de données ou d'un URI de métadonnées direct.

Pour plus d'informations, reportez-vous à Prise en charge d'Iceberg sur les exemples OCI Data Flow et à Formats d'URI DBMS_CLOUD.

Paramètres de format d'échantillon

Procédure CREATE_EXTERNAL_TABLE pour les fichiers Avro, ORC ou Parquet

Cette procédure avec le paramètre format type défini sur la valeur avro, orc ou parquet crée une table externe avec des fichiers au format Avro, ORC ou Parquet dans le cloud ou dans un répertoire.

Vous pouvez ainsi exécuter des requêtes sur des données externes à partir d'une base de données Autonomous AI.

Syntaxe

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    file_uri_list    IN CLOB,
    column_list      IN CLOB,
    field_list       IN CLOB DEFAULT,
    format           IN CLOB DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table externe.
credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Ce paramètre n'est pas utilisé lorsque vous indiquez un répertoire avec file_uri_list.

file_uri_list

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

URI de fichier source cloud

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Cette option est uniquement prise en charge avec les tables externes créées sur un fichier dans Object Storage.

Exemple :

file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.parquet'

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

Répertoire

Vous pouvez indiquer un répertoire et un ou plusieurs noms de fichier ou utiliser une liste de répertoires et de noms de fichier séparés par des virgules. Le format pour spécifier un répertoire est :'MY_DIR:filename.ext'. Par défaut, le nom de répertoire MY_DIR est un objet de base de données et ne tient pas compte de la casse. Ce nom de fichier distingue les majuscules des minuscules.

Vous pouvez utiliser des caractères génériques pour indiquer des noms de fichier dans un répertoire. Le caractère "*" peut être utilisé comme caractère générique pour représenter plusieurs caractères. Le caractère "?" peut être utilisé comme caractère générique pour représenter un seul caractère. Par exemple :'MY_DIR:*" ou 'MY_DIR:test?'

Pour spécifier plusieurs répertoires, utilisez une liste de répertoires séparés par des virgules : par exemple :'MY_DIR1:*, MY_DIR2:test?'

Utilisez des guillemets doubles pour indiquer un nom de répertoire sensible à la casse. Par exemple :'"my_dir1":*, "my_dir2":Test?'

Pour inclure un guillemet, utilisez deux guillemets. Par exemple :'MY_DIR:''filename.ext'. Cela indique que filename commence par un guillemet (').

column_list

(Facultatif) Lorsque ce champ est indiqué, il remplace le paramètre format->schema qui indique que le schéma, les colonnes et les types de données sont dérivés automatiquement. Pour plus de détails, reportez-vous au paramètre de format.

Lorsque la valeur column_list est indiquée pour la source Avro, ORC ou Parquet, les noms de colonne doivent correspondre aux colonnes trouvées dans le fichier. Les types de données Oracle doivent être mappés correctement avec les types de données Avro, ORC ou Parquet.

Pour plus d'informations sur les fichiers Parquet, reportez-vous à Mise en correspondance du parquet de package DBMS_CLOUD avec le type de données Oracle

Pour plus d'informations sur les fichiers ORC, reportez-vous à la section DBMS_CLOUD Package ORC to Oracle Data Type Mapping.

Pour plus d'informations sur les fichiers Avro, reportez-vous à la section DBMS_CLOUD Package Avro to Oracle Data Type Mapping.

field_list

Ignoré pour les fichiers Avro, ORC ou Parquet.

Les champs de la source correspondent aux colonnes de la table externe par nom. Les types de données source sont convertis en types de données de colonne de table externe.

For ORC files, see DBMS_CLOUD Package ORC to Oracle Data Type Mapping

Pour plus d'informations sur les fichiers Parquet, reportez-vous à Mise en correspondance du parquet de package DBMS_CLOUD avec le type de données Oracle.

Pour plus d'informations sur les fichiers Avro, reportez-vous à la section DBMS_CLOUD Package Avro to Oracle Data Type Mapping.

format Pour plus d'informations sur les fichiers source Avro, ORC ou Parquet type, reportez-vous à Options de format de package DBMS_CLOUD pour Avro, ORC ou Parquet.

Exemples 

A savoir : Pour plus d'informations sur la mise en correspondance des noms de colonne et l'utilisation de la conversion des noms de colonne dans Oracle SQL, voir Package DBMS_CLOUD Avro, ORC et Parquet vers Oracle.

Procédure CREATE_EXTERNAL_TEXT_INDEX

Cette procédure crée un index de texte sur les fichiers Object Storage.

La procédure CREATE_EXTERNAL_TEXT_INDEX crée un index de texte sur les fichiers Object Storage indiqués à l'emplacement location_uri. L'index est actualisé à intervalles réguliers, pour tous les nouveaux ajouts ou suppressions effectués avec des fichiers sur l'URI d'emplacement.

Syntaxe

DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
      credential_name  IN  VARCHAR2 DEFAULT NULL,
      location_uri     IN  VARCHAR2,
      index_name       IN  VARCHAR2,
      format           IN  CLOB     DEFAULT NULL
);

Paramètres

Paramètre Description
credential_name

Nom des données d'identification permettant d'accéder à l'emplacement de stockage d'objet cloud. Pour les URI de bucket publics, pré-authentifiés ou pré-signés, une valeur NULL peut être indiquée.

Si vous ne fournissez pas de valeur credential_name, credential_name est défini sur une valeur NULL.

location_uri

Ce paramètre spécifie une liste d'URI de fichier source, séparés par des virgules.

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Ce paramètre est obligatoire.

URI de fichier source cloud

Ce paramètre spécifie une liste d'URI de fichier source séparés par des virgules ou un ou plusieurs répertoires et fichiers source.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE.

Exemple d'utilisation d'expressions régulières :

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv'

Exemple avec des caractères génériques :

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE.

index_name Spécifie le nom de l'index que vous créez sur les fichiers situés à l'emplacement `location_uri`.

Ce paramètre est obligatoire.
format

Spécifie des options de configuration supplémentaires. Les options sont indiquées sous forme de chaîne JSON.

Les options de format prises en charge sont les suivantes :

refresh_rate : indique la fréquence en minutes à laquelle l'index local est actualisé. Les nouveaux téléchargements et suppressions de fichier entraînent une actualisation de l'index. La valeur par défaut est de 5 minutes.

binary_files : indique si le contenu des fichiers à indexer est binaire. Par exemple, PDF, MS-Word, La valeur par défaut est FALSE.

stop_words : indique qu'une liste de mots d'arrêt peut être fournie lorsque vous créez des index.

La valeur stop_words indique s'il s'agit d'une liste de mots stop ou d'une table de mots stop. Lorsqu'un tableau JSON est fourni, le paramètre des mots d'arrêt est traité comme une liste, sinon le paramètre des mots d'arrêt est traité comme un nom de table dont la colonne "STOP_WORDS" est utilisée pour lire la liste des mots d'arrêt.

Vous pouvez spécifier des mots d'arrêt à l'aide des méthodes suivantes :

  • Tableau JSON : par exemple : format := '{"stop_words":["king","queen"]}'
  • Nom de table de mots d'arrêt : par exemple : format := '{"stop_words":"STOP_WORDS_TABLE"}'

Si vous ne fournissez pas de paramètre format, format est défini sur une valeur NULL.

Exemple

BEGIN
DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
        credential_name => 'DEFAULT_CREDENTIAL',
        location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/ts_data/'
        index_name      => 'EMP',
        format          => JSON_OBJECT ('refresh_rate' value 10)
);
END;
/

Procédure CREATE_HYBRID_PART_TABLE

Cette procédure crée une table partitionnée hybride. Vous pouvez ainsi exécuter des requêtes sur des données partitionnées hybrides à partir d'une base de données Autonomous AI à l'aide d'objets et de fichiers de base de données dans le cloud ou d'objets et de fichiers de base de données dans un répertoire.

Syntaxe

DBMS_CLOUD.CREATE_HYBRID_PART_TABLE (
    table_name           IN VARCHAR2,
    credential_name      IN VARCHAR2,
    partitioning_clause  IN CLOB,
    column_list          IN CLOB,
    field_list           IN CLOB DEFAULT,
    format               IN CLOB DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table externe.
credential_name Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.
partitioning_clause

Spécifie la clause de partitionnement complète, y compris les informations d'emplacement pour les partitions individuelles.

Pour utiliser des répertoires, la clause de partitionnement prend en charge les valeurs LOCATION et DEFAULT DIRECTORY.

Vous pouvez utiliser des caractères génériques ainsi que des expressions régulières dans les noms de fichier dans les URI de fichier source cloud.

Les expressions régulières ne peuvent être utilisées que lorsque le paramètre regexuri format est défini sur TRUE.

Les caractères "*" et " ?" sont considérés comme des caractères génériques lorsque le paramètre regexuri est défini sur FALSE. Lorsque le paramètre regexuri est défini sur TRUE, les caractères "*" et " ?" font partie du modèle d'expression régulière indiqué.

Les modèles d'expression régulière sont uniquement pris en charge pour le nom de fichier ou le chemin de sous-dossier dans vos URI et la correspondance de modèle est identique à celle effectuée par la fonction REGEXP_LIKE. Les modèles d'expression régulière ne sont pas pris en charge pour les noms de répertoire.

Exemple :

partitioning_clause => 'partition by range (col1) (partition p1 values less than (1000) external location ( ''https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.txt''),...

Pour plus d'informations sur la condition REGEXP_LIKE, reportez-vous à Condition REGEXP_LIKE dans Référence de langage SQL Oracle Database 19c ou Référence de langage SQL Oracle Database 26ai.

column_list Liste des noms et des types de données de colonne pour la table externe, séparés par des virgules.
field_list Identifie les champs dans les fichiers source et leurs types de données. La valeur par défaut est NULL, ce qui signifie que les champs et leur type de données sont déterminés par le paramètre column_list. La syntaxe de cet argument est identique à la clause field_list dans les tables externes Oracle standard. Pour plus d'informations, reportez-vous à field_list dans Utilitaires Oracle Database 19c ou Utilitaires Oracle Database 26ai.
format Options décrivant le format des fichiers source. Pour obtenir la liste des options et découvrir comment spécifier les valeurs, reportez-vous à Paramètre de format.

Remarques sur l'utilisation

Exemples 

BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
      table_name =>'HPT1',
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
                                    ( ''&base_URL/file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) external location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000)
                                 )'
     );
   END;
/
BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
    table_name  => 'HPT1',
    format      => json_object('delimiter'value ',', 'recorddelimiter'value 'newline'),
    column_list => 'NAME VARCHAR2(30), GENDER VARCHAR2(10), BALANCE number',
    partitioning_clause => 'partition by range (B  2  ALANCE)
               (partition p1 values less than (1000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Scott_male_1000.csv''),
                partition p2 values less than (2000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Mary_female_3000.csv''),
                partition p3 values less than (3000))' );
END;
/

Procédure DELETE_ALL_OPERATIONS

Cette procédure efface toutes les opérations de chargement de données consignées dans la table user_load_operations de votre schéma, ou toutes les opérations de chargement de données du type spécifié, comme indiqué dans le paramètre type.

Syntaxe

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

Paramètres

Paramètre Description
type

Indique le type d'opération à supprimer. Les valeurs de type se trouvent dans la colonne TYPE de la table user_load_operations.

Si aucune valeur type n'est spécifiée, toutes les lignes sont supprimées.

Remarque sur l'utilisation

DBMS_CLOUD.DELETE_ALL_OPERATIONS ne supprime pas les opérations en cours d'exécution (opérations ayant le statut "En cours d'exécution").

Procédure DELETE_FILE

Cette procédure enlève le fichier spécifié du répertoire indiqué sur Autonomous AI Database.

Syntaxe

DBMS_CLOUD.DELETE_FILE (
      directory_name     IN VARCHAR2,
      file_name          IN VARCHAR2,
      force              IN BOOLEAN DEFAULT FALSE);

Paramètres

Paramètre Description
directory_name Nom du répertoire sur l'instance de base de données Autonomous AI.
file_name Nom du fichier à enlever.
force Ignorer et ne pas signaler les erreurs si le fichier n'existe pas. Les valeurs valides sont : TRUE et FALSE. La valeur par défaut est FALSE.

Remarque : pour exécuter DBMS_CLOUD.DELETE_FILE avec un utilisateur autre qu'ADMIN, vous devez lui accorder des privilèges d'écriture sur le répertoire qui contient le fichier. Par exemple, exécutez la commande suivante en tant qu'ADMIN pour accorder des privilèges d'écriture à atpc_user :

GRANT WRITE ON DIRECTORY data_pump_dir TO atpc_user;

Exemple

BEGIN
   DBMS_CLOUD.DELETE_FILE(
      directory_name =>  'DATA_PUMP_DIR',
      file_name => 'exp1.dmp' );
   END;
/

Procédure DELETE_OBJECT

Cette procédure supprime l'objet spécifié de la banque d'objets.

Syntaxe

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       force                IN BOOLEAN DEFAULT FALSE);

Paramètres

Paramètre Description
credential_name Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.
object_uri URI d'objet ou de fichier de l'objet à supprimer. Le format de l'URI dépend du service Cloud Object Storage que vous utilisez. Pour plus de détails, reportez-vous à Formats d'URI de stockage d'objet cloud.
force Ignorer et ne pas signaler les erreurs si l'objet n'existe pas. Les valeurs valides sont : TRUE et FALSE. La valeur par défaut est FALSE.

Exemple

BEGIN
   DBMS_CLOUD.DELETE_OBJECT(
       credential_name => 'DEF_CRED_NAME',
       object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp' );
   END;
/

Procédure DELETE_OPERATION

Cette procédure efface les entrées de chargement de données pour l'ID d'opération indiqué consignées dans les tables user_load_operations ou dba_load_operations de votre schéma.

Syntaxe

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

Paramètres

Paramètre Description
id Indique l'ID d'opération associé aux entrées de fichier journal à supprimer.

Exemple

SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);

Procédure DROP_EXTERNAL_TEXT_INDEX

Cette procédure supprime l'index de texte sur les fichiers Object Storage.

La procédure DROP_EXTERNAL_TEXT_INDEX supprime l'index spécifié créé avec la procédure CREATE_EXTERNAL_TEXT_INDEX.

Syntaxe

DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
      index_name       IN  VARCHAR2,
);

Paramètres

Paramètre Description
index_name

Spécifie le nom de l'index que vous supprimez.

Le nom de l'index doit correspondre au nom fourni au moment de sa création.

Ce paramètre est obligatoire.

Exemple

BEGIN
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
        index_name => 'EMP',
);
END;
/

Procédure EXPORT_DATA

Cette procédure exporte les données de la base de données Autonomous AI en fonction du résultat d'une requête. Cette procédure est surchargée et prend en charge l'écriture de fichiers dans le cloud ou dans un répertoire.

En fonction du paramètre format type, la procédure exporte les fichiers vers le cloud ou vers un emplacement de répertoire en tant que fichiers texte au format CSV, JSON, Parquet ou XML.

Syntaxe

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB,
      format            IN CLOB,
      query             IN CLOB);

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB DEFAULT NULL,
      format            IN CLOB DEFAULT NULL,
      query             IN CLOB DEFAULT NULL,
      operation_id      OUT NOCOPY NUMBER);

Paramètres

Paramètre Description
credential_name

Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.

Lorsque le paramètre d'informations d'identification n'est pas inclus, cela indique la sortie vers un répertoire.
file_uri_list

Il existe différentes formes, selon la valeur du paramètre de format et selon que vous incluez ou non un paramètre d'informations d'identification :

  • Lorsque la valeur du paramètre format type est json : le fichier JSON sur la banque d'objets ou à l'emplacement de répertoire indiqué est enregistré avec un nom de fichier généré en fonction de la valeur du paramètre file_uri_list. Pour plus d'informations, reportez-vous à Dénomination de fichier pour la sortie texte (CSV, JSON, Parquet ou XML).

  • Lorsque la valeur du paramètre format type est datapump, file_uri_list est une liste de fichiers dump séparés par des virgules. Indique les fichiers à créer dans la banque d'objets. L'utilisation de caractères génériques et de caractères de substitution n'est pas prise en charge dans file_uri_list.

  • Lorsque le paramètre credential_name n'est pas indiqué, vous indiquez un nom de répertoire dans file_uri_list.

Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour plus de détails, reportez-vous à Formats d'URI de stockage d'objet cloud.
format

Chaîne JSON qui fournit des options de format d'export.

L'option prise en charge est :

  • type : L'option type format est requise et doit avoir l'une des valeurs suivantes : csv | datapump | json | parquet | xml.

Reportez-vous à Options de format de package DBMS_CLOUD pour EXPORT_DATA

query

Utilisez ce paramètre pour indiquer une instruction SELECT afin que seules les données requises soient exportées. La requête détermine le contenu des fichiers que vous exportez en tant que fichiers texte CSV, JSON, Parquet ou XML, ou en tant que fichiers dump. Exemple : 

SELECT warehouse_id, quantity FROM inventories

Lorsque la valeur format type est json, chaque résultat de requête est vérifié et s'il ne s'agit pas de JSON, comme déterminé par la fonction : JSON_OBJECT_T.parse(), DBMS_CLOUD.EXPORT_DATA transforme la requête pour inclure la fonction JSON_OBJECT afin de convertir la ligne en JSON. Pour plus d'informations, reportez-vous à JSON_OBJECT dans le manuel Oracle Database 19c SQL Language Reference ou Oracle Database 26ai SQL Language Reference et JSON_OBJECT_T Object Type dans le manuel Oracle Database 19c PL/SQL Packages and Types Reference ou Oracle Database 26ai PL/SQL Packages and Types Reference.

Exemple :

SELECT JSON_OBJECT(* RETURNING CLOB) from(SELECT warehouse_id, quantity FROM inventories)
operation_id Utilisez ce paramètre pour suivre la progression et la fin de l'opération d'export sous l'ID correspondant dans la vue USER_LOAD_OPERATIONS.

Remarques sur l'utilisation

Notes d'utilisation pour `DBMS_CLOUD.EXPORT_DATA` avec sortie dans un répertoire

ORA-31641: unable to create dump file  "/u02/exports/123.dmp"
ORA-27038: created file already exists

Exemples 

Exemple : DBMS_CLOUD.EXPORT_DATA avec le paramètre de format type avec la valeur json.

BEGIN
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.json',
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'json', 'compression' value 'gzip'));
     );
   END;
/

Exemple : DBMS_CLOUD.EXPORT_DATA avec le paramètre de format type avec la valeur xml.

BEGIN
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.xml',
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'xml', 'compression' value 'gzip'));
     );
   END;
/

Exemple : DBMS_CLOUD.EXPORT_DATA avec le paramètre de format type avec la valeur csv.

BEGIN
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp.csv',
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'csv', 'delimiter' value '|', 'compression' value 'gzip', 'header' value true ));
     );
   END;
/

Procédure et fonction GET_OBJECT

Cette procédure est surchargée. Cette procédure lit un objet à partir du stockage d'objet cloud et le copier vers la base de données Autonomous AI. Le formulaire de fonction lit un objet à partir du stockage d'objet cloud et renvoie une valeur BLOB vers la base de données Autonomous AI.

Syntaxe

DBMS_CLOUD.GET_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2 DEFAULT  NULL,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL);
DBMS_CLOUD.GET_OBJECT(
       credential_name      IN VARCHAR2 DEFAULT NULL,
       object_uri           IN VARCHAR2,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL)
RETURN BLOB;

Paramètres

Paramètre Description
credential_name Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.
object_uri URI de l'objet ou du fichier. Le format de l'URI dépend du service Cloud Object Storage que vous utilisez. Pour plus de détails, reportez-vous à Formats d'URI de stockage d'objet cloud.
directory_name Nom du répertoire dans la base de données. (Voir la note de bas de page 1 ci-dessous)
file_name Indique le nom du fichier à créer. Si le nom du fichier n'est pas spécifié, il est défini sur ce qui suit la dernière barre oblique dans le paramètre object_uri. Pour les cas particuliers, par exemple lorsque le nom du fichier contient des barres obliques, utilisez le paramètre file_name.
startoffset Décalage, en octets, à partir duquel la procédure commence la lecture.
endoffset Décalage, en octets, auquel la procédure arrête la lecture.
compression Spécifie la compression utilisée pour stocker l'objet. Lorsque compression est défini sur "AUTO", le fichier n'est pas compressé (la valeur "AUTO" implique que l'objet spécifié avec object_uri est compressé avec Gzip).

Note de bas de page 1

Remarque : pour exécuter DBMS_CLOUD.GET_OBJECT avec un utilisateur autre qu'ADMIN, vous devez accorder à cet utilisateur des privilèges WRITE sur le répertoire. Par exemple, exécutez la commande suivante en tant qu'ADMIN pour accorder des privilèges d'écriture à atpc_user :

GRANT WRITE ON DIRECTORY data_pump_dir TO atpc_user;

Valeurs retournées

Le formulaire de fonction lit à partir de la banque d'objets et DBMS_CLOUD.GET_OBJECT renvoie une valeur BLOB.

Exemples 

BEGIN
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt',
     directory_name => 'DATA_PUMP_DIR');
END;
/

Exemple : pour lire des données alphanumériques à partir d'un fichier dans la banque d'objets.

SELECT to_clob(
     DBMS_CLOUD.GET_OBJECT(
       credential_name => 'OBJ_STORE_CRED',
       object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt'))
FROM DUAL;

Exemple : pour ajouter une image stockée dans la banque d'objets dans un fichier BLOB de la base de données.

DECLARE
   l_blob BLOB := NULL;
BEGIN
   l_blob := DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/MyImage.gif' );
END;
/

Dans cet exemple, namespace-string est l'espace de noms Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Présentation des espaces de noms Object Storage.

Fonction LIST_FILES

Cette fonction liste les fichiers présents dans le répertoire spécifié. Les résultats incluent les noms de fichier et les métadonnées supplémentaires sur les fichiers, telles que la taille de fichier en octets, l'horodatage de création et l'horodatage de dernière modification.

Syntaxe

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

Paramètres

Paramètre Description
directory_name Nom du répertoire dans la base de données. Ce paramètre prend en charge les caractères génériques.

Remarques sur l'utilisation

Exemples 

Exemple : utilisation de la requête suivante pour utiliser DBMS_CLOUD.LIST_FILES en tant que fonction pipelinée qui renvoie une ligne pour chaque fichier.

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR');
OBJECT_NAME       BYTES   CHECKSUM      CREATED              LAST_MODIFIED
------------ ---------- ----------    ---------------------  ---------------------
cwallet.sso        2965               2018-12-12T18:10:47Z   2019-11-23T06:36:54Z

Vous pouvez également utiliser DBMS_CLOUD.LIST_FILES avec la syntaxe DIRECTORY:FILE, en spécifiant un fichier ou en utilisant des caractères génériques. * et ? sont les caractères génériques pris en charge.

Exemple : pour répertorier tous les fichiers CSV commençant par "f" dans le répertoire DATA_PUMP_DIR à l'aide d'un caractère générique.

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f*.csv');

Exemple : pour répertorier le fichier f1.csv dans le répertoire DATA_PUMP_DIR en indiquant le nom du fichier.

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f1.csv');

Fonction LIST_OBJECTS

Cette fonction répertorie les objets présents à l'emplacement spécifié dans la banque d'objets. Les résultats incluent les noms d'objet et les métadonnées supplémentaires sur les objets, telles que la taille, le checksum, l'horodatage de création et l'horodatage de dernière modification.

Syntaxe

DBMS_CLOUD.LIST_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

Paramètres

Paramètre Description
credential_name Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.
location_uri

URI de dossier ou de bucket Object Storage. Le format des URI dépend du service Cloud Object Storage que vous utilisez. Pour en savoir plus, reportez-vous àFormats d'URI de stockage d'objet cloud.

Les caractères génériques sont pris en charge pour répertorier de manière sélective les fichiers ou sous-dossiers dans un URI. Les caractères "*" et "?" sont considérés comme des caractères génériques.

Exemple avec des caractères génériques :

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv'

Remarques sur l'utilisation

Exemple

Il s'agit d'une fonction pipelinée qui renvoie une ligne pour chaque objet. Par exemple, générez la requête suivante pour utiliser cette fonction :

SELECT * FROM DBMS_CLOUD.LIST_OBJECTS('OBJ_STORE_CRED',
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/');
OBJECT_NAME   BYTES              CHECKSUM                       CREATED         LAST_MODIFIED
------------ ---------- -------------------------------- --------------------- --------------------
cwallet.sso   2965      2339a2731ba24a837b26d344d643dc07 2019-11-23T06:36:54Z

Dans cet exemple, namespace-string est l'espace de noms Oracle Cloud Infrastructure Object Storage et bucketname est le nom du bucket. Pour plus d'informations, reportez-vous à Présentation des espaces de noms Object Storage.

Procédure MOVE_OBJECT

Cette procédure déplace un objet d'un bucket ou dossier Cloud Object Storage vers un autre.

Le dossier ou le bucket source et cible peuvent se trouver dans le même fournisseur de banque d'objets cloud ou dans un autre fournisseur.

Lorsque la source et la cible se trouvent dans des banques d'objets distinctes ou ont des comptes différents avec le même fournisseur cloud, vous pouvez donner des noms d'informations d'identification distincts pour les emplacements source et cible.

Par défaut, le nom des informations d'identification source est également utilisé par l'emplacement cible lorsque le nom des informations d'identification cible n'est pas fourni.

Syntaxe

DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

Paramètres

Paramètre Description
source_credential_name

Nom des infos d'identification permettant d'accéder au stockage d'objet cloud source.

Si vous ne fournissez pas de valeur source_credential_name, credential_name est défini sur NULL.

source_object_uri

Spécifie l'URI, qui pointe vers l'emplacement du dossier ou du bucket Object Storage source.

Ce paramètre est obligatoire.

Le format des URI dépend du service Cloud Object Storage. Pour plus d'informations, reportez-vous à Formats d'URI de stockage d'objet cloud.

target_object_uri

Indique l'URI du bucket ou dossier Object Storage cible, où les fichiers doivent être déplacés.

Ce paramètre est obligatoire.

Le format des URI dépend du service Cloud Object Storage. Pour plus d'informations, reportez-vous à Formats d'URI de stockage d'objet cloud.

target_credential_name

Nom des données d'identification permettant d'accéder à l'emplacement de stockage d'objet cloud cible.

Si vous ne fournissez pas de valeur target_credential_name, target_object_uri est défini sur la valeur source_credential_name.

Exemple

BEGIN
DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

Procédure PUT_OBJECT

Cette procédure est surchargée. Dans un formulaire, la procédure copie un fichier d'Autonomous AI Database vers Cloud Object Storage. Dans un autre formulaire, la procédure copie une valeur BLOB d'Autonomous AI Database vers Cloud Object Storage.

Syntaxe

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2
       compression          IN VARCHAR2 DEFAULT  NULL);
DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB
       compression          IN VARCHAR2 DEFAULT  NULL);

Paramètres

Paramètre Description
credential_name Nom des informations d'identification permettant d'accéder au stockage d'objet cloud.
object_uri URI de l'objet ou du fichier. Le format de l'URI dépend du service Cloud Object Storage que vous utilisez. Pour plus de détails, reportez-vous à Formats d'URI de stockage d'objet cloud.
directory_name Nom du répertoire dans la base de données. (Voir la note de bas de page 1 ci-dessous)
contents Indique le BLOB à copier de la base de données Autonomous AI vers le stockage d'objet cloud.
file_name Nom du fichier dans le répertoire spécifié.
compression

Spécifie la compression utilisée pour stocker l'objet.

La valeur par défaut est NULL

Note de bas de page 1

Remarque : pour exécuter DBMS_CLOUD.PUT_OBJECT avec un utilisateur autre qu'ADMIN, vous devez lui accorder des privilèges d'accès en lecture sur le répertoire. Par exemple, exécutez la commande suivante en tant qu'ADMIN pour accorder les privilèges de lecture à atpc_user :

GRANT READ ON DIRECTORY data_pump_dir TO atpc_user;

Exemple

Pour gérer les données BLOB après le traitement dans la base de données, puis les stocker directement dans un fichier de la banque d'objets, procédez comme suit :

DECLARE
      my_blob_data BLOB;
BEGIN
 /* Some processing producing BLOB data and populating my_blob_data */
DBMS_CLOUD.PUT_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/my_new_file',
     contents => my_blob_data));
END;
/

Remarques sur l'utilisation

En fonction de votre stockage d'objet cloud, la taille de l'objet que vous transférez est limitée comme suit :

Service Cloud Object Storage Limite de taille de transfert d'objet
Oracle Cloud Infrastructure Object Storage 50 GB
Amazon S3 5 GB
Stockage BLOB Azure 256 Mo
Compatible avec Amazon S3 Défini par le fournisseur de banque d'objets. Pour plus d'informations, reportez-vous à la documentation du fournisseur.

La banque d'objets Oracle Cloud Infrastructure ne permet pas d'écrire des fichiers dans un bucket public sans fournir d'informations d'identification (Oracle Cloud Infrastructure permet aux utilisateurs de télécharger des objets à partir de buckets publics). Par conséquent, vous devez fournir un nom d'informations d'identification avec des informations d'identification valides pour stocker un objet dans un bucket public Oracle Cloud Infrastructure à l'aide de PUT_OBJECT.

Pour plus d'informations, reportez-vous à Formats d'URI de stockage d'objet cloud.

Procédure SYNC_EXTERNAL_PART_TABLE

Cette procédure simplifie la mise à jour d'une table partitionnée externe à partir de fichiers dans le cloud. Exécutez cette procédure chaque fois que de nouvelles partitions sont ajoutées ou lorsque des partitions sont supprimées de la source de la banque d'objets pour la table partitionnée externe.

Syntaxe

DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
	table_name        IN VARCHAR2,
	schema_name       IN VARCHAR2 DEFAULT,
	update_columns    IN BOOLEAN DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la Table cible. La table cible doit être créée avant d'exécuter DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE.
schema_name Nom du schéma dans lequel réside la table cible. La valeur par défaut est NULL, ce qui signifie que la table cible se trouve dans le même schéma que l'utilisateur qui exécute la procédure.
update_columns

Les nouveaux fichiers peuvent apporter une modification au schéma. Les mises à jour prises en charge sont les suivantes : nouvelles colonnes, colonnes supprimées. Les mises à jour des colonnes existantes, par exemple une modification du type de données, génèrent des erreurs.

Valeur par défaut : False

Procédure VALIDATE_EXTERNAL_PART_TABLE

Cette procédure valide les fichiers source pour une table partitionnée externe, génère les informations de journal et stocke les lignes qui ne correspondent pas aux options de format indiquées pour la table externe dans une table badfile sur la base de données Autonomous AI. La forme surchargée permet d'utiliser le paramètre operation_id.

Syntaxe

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);
DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table externe.
operation_id Utilisez ce paramètre pour suivre la progression et le statut final de l'opération de chargement sous l'ID correspondant dans la vue USER_LOAD_OPERATIONS.
partition_name Si elle est définie, seule une partition spécifique est validée. Si aucune valeur n'est indiquée, lisez toutes les partitions de manière séquentielle jusqu'à ce que rowcount soit atteint.
subpartition_name Si elle est définie, seule une sous-partition spécifique est validée. Si aucune valeur n'est indiquée, la lecture de toutes les partitions ou sous-partitions externes est séquentielle jusqu'à ce que rowcount soit atteint.
schema_name Nom du schéma dans lequel réside la table externe. La valeur par défaut est NULL, ce qui signifie que la table externe se trouve dans le même schéma que l'utilisateur qui exécute la procédure.
rowcount Nombre de lignes à analyser. La valeur par défaut est NULL, ce qui signifie que toutes les lignes des fichiers source sont analysées.
partition_key_validation A usage interne uniquement. N'utilisez pas ce paramètre.
stop_on_error Détermine si la validation doit s'arrêter lorsqu'une ligne est rejetée. La valeur par défaut est TRUE, ce qui signifie que la validation s'arrête à la première ligne rejetée. La définition de la valeur sur FALSE indique que la validation ne s'arrête pas à la première ligne rejetée et valide toutes les lignes jusqu'à la valeur indiquée pour le paramètre rowcount.

Procédure VALIDATE_EXTERNAL_TABLE

Cette procédure valide les fichiers source pour une table externe, génère une information sur le journal et stocke les lignes qui ne correspondent pas aux options de format indiquées pour la table externe dans une table badfile sur Autonomous AI Database. La forme surchargée permet d'utiliser le paramètre operation_id.

Syntaxe

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE (
	table_name      IN VARCHAR2,
	schema_name     IN VARCHAR2 DEFAULT,
	rowcount        IN NUMBER DEFAULT,
	stop_on_error   IN BOOLEAN DEFAULT);
DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE(
	table_name      IN VARCHAR2,
	operation_id    OUT NOCOPY NUMBER,
	schema_name     IN VARCHAR2 DEFAULT NULL,
	rowcount        IN NUMBER DEFAULT 0,
	stop_on_error   IN BOOLEAN DEFAULT TRUE);

Paramètres

Paramètre Description
table_name Nom de la table externe.
operation_id Utilisez ce paramètre pour suivre la progression et le statut final de l'opération de chargement sous l'ID correspondant dans la vue USER_LOAD_OPERATIONS.
schema_name Nom du schéma dans lequel réside la table externe. La valeur par défaut est NULL, ce qui signifie que la table externe se trouve dans le même schéma que l'utilisateur qui exécute la procédure.
rowcount Nombre de lignes à analyser. La valeur par défaut est NULL, ce qui signifie que toutes les lignes des fichiers source sont analysées.
stop_on_error

Détermine si la validation doit s'arrêter lorsqu'une ligne est rejetée. La valeur par défaut est TRUE, ce qui signifie que la validation s'arrête à la première ligne rejetée. La définition de la valeur sur FALSE indique que la validation ne s'arrête pas à la première ligne rejetée et valide toutes les lignes jusqu'à la valeur indiquée pour le paramètre rowcount.

Si la table externe fait référence à des fichiers Avro, ORC ou Parquet, la validation s'arrête à la première ligne rejetée.

Lorsque la table externe indique que le paramètre format type est défini sur la valeur avro, orc ou parquet, le paramètre stop_on_error a toujours la valeur TRUE. Par conséquent, le fichier badfile de la table sera toujours vide pour une table externe faisant référence aux fichiers Avro, ORC ou Parquet.

Remarque sur l'utilisation

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE fonctionne avec les tables externes partitionnées et les tables partitionnées hybrides. Cela permet de lire les données de toutes les partitions externes jusqu'à ce que rowcount soit atteint ou que stop_on_error s'applique. Vous n'avez pas le contrôle sur quelle partition, ou parties d'une partition, est lue dans quel ordre.

Procédure VALIDATE_HYBRID_PART_TABLE

Cette procédure valide les fichiers source pour la table partitionnée hybride, génère les informations de journal et stocke les lignes qui ne correspondent pas aux options de format indiquées pour la table hybride dans une table badfile sur la base de données Autonomous AI. La forme surchargée permet d'utiliser le paramètre operation_id.

Syntaxe

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);
DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       subpartition_name          IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

Paramètres

Paramètre Description
table_name Nom de la table externe.
operation_id Utilisez ce paramètre pour suivre la progression et le statut final de l'opération de chargement sous l'ID correspondant dans la vue USER_LOAD_OPERATIONS.
partition_name Si elle est définie, seule une partition spécifique est validée. Si aucune valeur n'est indiquée, la lecture de toutes les partitions externes est séquentielle jusqu'à ce que rowcount soit atteint.
subpartition_name Si elle est définie, seule une sous-partition spécifique est validée. Si aucune valeur n'est indiquée, la lecture de toutes les partitions ou sous-partitions externes est séquentielle jusqu'à ce que rowcount soit atteint.
schema_name Nom du schéma dans lequel réside la table externe. La valeur par défaut est NULL, ce qui signifie que la table externe se trouve dans le même schéma que l'utilisateur qui exécute la procédure.
rowcount Nombre de lignes à analyser. La valeur par défaut est NULL, ce qui signifie que toutes les lignes des fichiers source sont analysées.
partition_key_validation A usage interne uniquement. N'utilisez pas ce paramètre.
stop_on_error Détermine si la validation doit s'arrêter lorsqu'une ligne est rejetée. La valeur par défaut est TRUE, ce qui signifie que la validation s'arrête à la première ligne rejetée. La définition de la valeur sur FALSE indique que la validation ne s'arrête pas à la première ligne rejetée et valide toutes les lignes jusqu'à la valeur indiquée pour le paramètre rowcount.

Contenu connexe