DBMS_CLOUD 程序包格式选项

DBMS_CLOUD 中的 format 参数指定源文件的格式。

指定格式参数的两种方式是:

format => '{"format_option" : “format_value” }'  

和:

format => json_object('format_option' value 'format_value'))

示例:

format => json_object('type' VALUE 'CSV')

要指定多个格式选项,请使用 "," 分隔值。

例如:

format => json_object('ignoremissingcolumns' value 'true', 'removequotes' value 'true', 
                           'dateformat' value 'YYYY-MM-DD-HH24-MI-SS', 'blankasnull' value 'true', 'logretention' value 7)

注意:

有关 Avro、ORC 或 Parquet 格式选项,请参见 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet

格式选项列中所述,在 format type 为 JSON 时,一组有限的格式选项对 DBMS_CLOUD.COPY_COLLECTIONDBMS_CLOUD.COPY_DATA 有效。

格式选项 说明 语法

blankasnull

设置为 true 时,将包含空格的字段加载为 Null。

blankasnull : true

默认值:False

characterset

使用 format JSON 和 COPY_DATA 有效

指定源文件的字符集

characterset: string

默认值:数据库字符集

columnpath

仅与 format JSON 和 COPY_DATA 一起使用

与需要从 JSON 记录中提取的字段相对应的 JSON 路径表达式的数组。数组中的每个 JSON 路径表达式都应遵循 Oracle Database 19c JSON Developer's GuideOracle Database 23ai JSON Developer's GuideSQL/JSON Path Expressions 中所述的规则。

仅与 JSON 和 DBMS_CLOUD.COPY_DATA 格式一起使用。

以字符串格式表示的 json 路径表达式的 JSON 数组。例如:'columnpath' value '["$.WEATHER_STATION_ID", "$.WEATHER_STATION_NAME"]'

compression

选项对 JSON 数据有效

指定源文件的压缩类型。

不支持 ZIP 归档格式。

指定值 auto 将检查压缩类型:gzip, zlib, std, bzip2

compression: auto|gzip|zlib|bzip2

默认值:空值,表示无压缩。

conversionerrors

如果行因数据类型转换错误而被拒绝,则相关列将存储为空值或相应行被拒绝。

conversionerrors : reject_record | store_null

默认值:reject_record

dateformat

指定源文件中的日期格式。格式选项 AUTO 搜索以下格式:

J 
MM-DD-YYYYBC 
MM-DD-YYYY 
YYYYMMDD HHMISS 
YYMMDD HHMISS 
YYYY.DDD 
YYYY-MM-DD

dateformat: string

默认值:数据库日期格式

delimiter

指定字段分隔符。

要使用特殊字符作为分隔符,请指定字符的 ASCII 代码的 HEX 值。例如,以下语句将 TAB 字符指定为分隔符:

format => json_object('delimiter' value 'X''9''')

delimiter: character

默认值 |(竖线字符)

detectfieldorder

指定外部数据文件中的字段的顺序与表中的列不同。使用每个外部数据文件的第一行检测字段的顺序,并将其映射到表的列。以不区分大小写的方式将外部数据文件中的字段名称与表列的名称进行比较。

此格式选项适用于以下过程:

  • DBMS_CLOUD.COPY_DATA

  • DBMS_CLOUD.CREATE_EXTERNAL_TABLE

  • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE

  • DBMS_CLOUD.CREATE_HYBRID_PART_TABLE

detectfieldorder 的限制:

  • 数据文件中的字段名称必须出现在第一个记录行中,且字段名称之间不得包含任何空格。

  • 字段名称记录中的字段分隔符必须与文件中数据的字段分隔符相同。

  • 不支持带引号的字段名称。以不区分大小写的方式将数据文件中的字段名称与外部表列的名称进行比较。

  • 字段名称中不允许嵌入字段分隔符。

  • 表中的列数必须与数据文件中的字段数匹配。

  • 此格式选项不适用于 Bigdata 或 Oracle Data Pump 格式,因为这些格式具有二进制文件格式的精确列元数据信息。

    当第一行包含字段名称时,文本格式、CSV、JSON、Parquet 或 XML 可以从此自动现场工单检测中受益。

有关详细信息,请参阅 Oracle Database 19c UtilitiesOracle Database 23ai Utilities 中的 FIELD NAMES 以及 ALL FILES 的说明。

detectfieldorder: true

默认值:false

enablelogs

格式选项 enablelogs 与以下 DBMS_CLOUD 过程一起使用:

  • COPY_DATA

  • COPY_COLLECTION

  • EXPORT_DATA

enablelogs 指定布尔值,当设置为 TRUE 时,将生成日志。设置为 FALSE 时,不会生成日志。

例如:

format => JSON_OBJECT('enablelogs' value FALSE)

enablelogs: false

默认值:true

encryption

格式选项 encryption 指定要将数据导出和导入对象存储以及从对象存储导入数据的加密和解密选项。

使用 encryption 指定以下参数来加密和解密:

  • user_defined_function:指定用于解密或加密指定 BLOB(二进制大对象)的全限定用户定义函数。它返回解密或加密的 BLOB。user_defined_functionencryption 的其他参数互斥。

    例如,ADMIN.DECRYPTION_CALLBACK

  • type:指定要解密或加密的 DBMS_CRYPTO 加密算法。

    type 接受 Block Cipher Algorithms + Block Cipher Chaining Modifiers + Block Cipher Padding Modifiers 格式的值。

    支持的块密码算法包括:

    • DBMS_CRYPTO.ENCRYPT_AES256

    支持的块密码链接修饰符包括:

    • DBMS_CRYPTO.CHAIN_CBC

    • DBMS_CRYPTO.CHAIN_CFB

    • DBMS_CRYPTO.CHAIN_ECB

    • DBMS_CRYPTO.CHAIN_OFB

    支持的块密码填充修饰符包括:

    • DBMS_CRYPTO.PAD_PKCS5

    • DBMS_CRYPTO.PAD_NONE

    • DBMS_CRYPTO.PAD_ZERO

    • DBMS_CRYPTO.PAD_ORCL

  • credential_name:指定用于存储加密密钥的身份证明。

如果未为这些参数指定值,则块密码链接修饰符和块密码填充修饰符值默认为 DBMS_CRYPTO.CHAIN_CBCDBMS_CRYPTO.PAD_PKCS5

格式选项 encryption 与以下 DBMS_CLOUD 过程一起使用:
  • 用于为以下过程传递要解密的参数:

    • DBMS_CLOUD.COPY_DATA

    • DBMS_CLOUD.CREATE_EXTERNAL_TABLE

    • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE

    • DBMS_CLOUD.CREATE_HYBRID_PART_TABLE

      对于 DBMS_CLOUD.CREATE_HYBRID_PART_TABLE,此选项仅适用于对象存储文件。

    • DBMS_CLOUD.COPY_COLLECTION

  • 用于传递参数以对以下过程进行加密:

    • DBMS_CLOUD.EXPORT_DATA

例如:

format => JSON_OBJECT('encryption' value json_object ('type' value DBMS_CRYPTO.ENCRYPT_AES256 + DBMS_CRYPTO.CHAIN_CBC + DBMS_CRYPTO.PAD_PKCS5, 'credential_name' value 'ENCRYPTION_CRED'))
encryption:value

其中 value 是为加密提供其他参数的 JSON 字符串:

type: value

指定加密类型。

credential_name: value

指定用于存储加密密钥的身份证明。

user_defined_function: value

指定用于解密或加密指定 BLOB(二进制大对象)的全限定用户定义函数。

endquote

数据可以用 quoteendquote 指定的两个分隔符括起来。指定时,加载期间会删除 quoteendquote 字符。

例如:

format => JSON_OBJECT(‘quote’ value ‘(’, ‘endquote’ value ‘)’)

endquote:character

默认值为 Null,表示无 endquote

escape

指定此项后,字符 "\" 用作转义符。

escape : true

默认值:false

ignoreblanklines

选项对 JSON 数据有效

设置为 true 时,将忽略空行。

ignoreblanklines : true

默认值:False

ignoremissingcolumns

如果 field_list 中的列数超过源文件中的列数,则额外的列将存储为空值。

ignoremissingcolumns : true

默认值 False

jsonpath

仅与 COPY_COLLECTION 一起使用

用于标识要加载的文档的 JSON 路径。

此选项仅对具有 DBMS_CLOUD.COPY_COLLECTION 的 JSON 收集数据有效。

jsonpath: string

默认值:空值

keyassignment

仅与 COPY_COLLECTION 一起使用

指定是将新集合创建为与 mongo 兼容的集合还是 SODA 集合。

当该值设置为 embedded_oid 时,将创建一个新集合作为与 mongo 兼容的集合。

默认情况下,不设置此参数,这意味着将创建一个新集合作为 SODA 集合。

keyassignment: embedded_oid

默认值:未设置 keyassignment

keypath

仅与 COPY_COLLECTION 一起使用

指定要作为 '_id' 值加载的数据中的属性。

如果指定了 keypath,则还必须将 keyassignment 值指定为 embedded_oid

将值设置为路径,例如 '$.mykey',以选择路径值作为 '_id' 值。

此参数是可选的,仅适用于加载到与 Mongo 兼容的集合。

如果未指定,则 Oracle 将生成一个 12 字节的唯一系统 ID,并将该 ID 填充为 '_id' 属性(如果加载的数据中尚不存在 '_id' 属性)。

keypath: string

默认值:未设置 keypath

设置 keypath 时,缺省的 string 值为 NULL

language

指定语言名称(例如,FRENCH),从语言可以派生区域设置相关信息。

language: string

默认值:空值

有关 Oracle 支持的语言列表,请参阅 Oracle Database 19c Database Globalization Support Guide 中的 Locale DataOracle Database 23ai Database Globalization Support Guide

logdir

指定用于确定保存 logfile_tablebadfile_table 文件的目录对象名称的字符串值。

缺省情况下,logdir 不区分大小写,但当指定的值用双引号括起来时,会保留大小写。

例如:

format => JSON_OBJECT ('logdir' value 'test_log')

上面的示例中指定的 logdir 格式选项将 logfile_tablebadfile_table 文件保存在 TEST_LOG 目录对象中。

format => JSON_OBJECT ('logdir' value '"test_log"')

上面的示例中指定的 logdir 格式选项将 logfile_tablebadfile_table 文件保存在 test_log 目录对象中。

logdir: string

默认值:DATA_PUMP_DIR

logprefix

指定用于确定 logfile_tablebadfile_table 文件前缀的字符串值。

日志表名称格式为: logprefix$operation_id

默认情况下,logprefix 为大写,但当指定的值用双引号括起来时,会保留大小写。

例如:

format => JSON_OBJECT ('logprefix' value 'TEST')

然后,日志文件使用 TEST 前缀,例如:TEST$2_LOGTEST$2_BAD

logprefix: string

默认值:COPY

logretention

指定保留 logfile_tablebadfile_table 文件的正整数持续时间(天)。

有效值:099999

例如:

format => JSON_OBJECT ('logretention' value 7)

logretention: number

默认值:2

maxdocsize

此选项仅对 JSON 数据有效

JSON 文档的最大大小。

maxdocsize: number

默认值:1 兆字节

允许的最大值:2 GB

numericcharacters

指定要用作组分隔符和小数字符的字符。

decimal_character :小数将数字的整数部分与小数部分分隔开。

group_separator :组分隔符用于分隔整数组(即千、百万、数十亿等)。

numericcharacters: 'decimal_character group_separator'

默认值:".,"

有关更多信息,请参见 NLS_NUMERIC_CHARACTERS Oracle Database 19c Database Globalization Support Guide Oracle Database 23ai Database Globalization Support Guide

numberformat

指定数字格式模型。数字格式模型会导致数字舍入到指定的有效位数。数字格式模型由一个或多个数字格式元素组成。

这与 numericcharacters 结合使用。

numberformat: number_format_model

默认值:派生自 NLS_TERRITORY 参数的设置

有关详细信息,请参阅 Oracle Database 19c SQL Language Reference 中的 Number Format ModelsOracle Database 23ai SQL Language Reference

partition_columns

格式选项 partition_columnsDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 一起使用,用于指定分区列从文件路径派生时的列名和数据类型,具体取决于数据文件的类型(结构化或非结构化):

  • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 包含 column_list 参数并且数据文件是非结构化的(例如 CSV 文本文件)时,partition_columns 不包括数据类型。例如,对于此类型的 partition_columns 规范,请使用如下格式:

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

    数据类型不是必需的,因为它是在 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE column_list 参数中指定的。

  • 如果 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 不包含 column_list 参数并且数据文件是结构化的,例如 Avro、ORC 或 Parquet 文件,则 partition_columns 选项包括数据类型。例如,下面显示了 partition_columns 规范:

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

如果数据文件是非结构化的,并且使用 partition_columns 指定了 type 子子句,则忽略 type 子子句。

对于不基于蜂窝格式的对象名称,partition_columns 指定的列的顺序必须与 file_uri_list 中对象名称中显示的顺序匹配。

 

quote

指定字段的引号字符,如果指定了此项,在加载期间将删除 quote 字符。

quote: character

默认值:Null 表示无引号

recorddelimiter

选项对 JSON 数据有效

指定记录分隔符。

缺省情况下,DBMS_CLOUD 会尝试自动查找正确的换行符作为分隔符。它首先在文件中搜索 Windows 新行字符 "\r\n"。如果找到 Windows 换行符,则将其用作过程中的所有文件的记录分隔符。如果未找到 Windows 换行符,则会搜索 UNIX/Linux 换行符 "\n",如果找到,则会使用 "\n" 作为过程中的所有文件的记录分隔符。

如果要覆盖默认行为,请显式指定此参数,例如:

format => json_object('recorddelimiter' VALUE '''\r\n''')

要指示没有记录分隔符,可以指定输入文件中未出现的 recorddelimiter。例如,要指示没有分隔符,请将控制字符 0x01 (SOH) 指定为 recorddelimiter 的值,并将 recorddelimiter 值设置为 "0x''01''"(JSON 文本中不出现此字符)。例如:

format => '{"recorddelimiter" : "0x''01''"}'

recorddelimiter 为每次过程调用设置一次。如果使用默认值 detected newline,则所有文件都使用相同的记录分隔符(如果检测到)。

recorddelimiter: character

默认值:检测到换行符

regexuri

格式选项 regexuri 与以下 DBMS_CLOUD 过程一起使用:

  • COPY_COLLECTION

  • COPY_DATA

  • CREATE_EXTERNAL_TABLE

  • CREATE_EXTERNAL_PART_TABLE

  • CREATE_HYBRID_PART_TABLE

regexuri 的值设置为 TRUE 时,可以在云源文件 URI 中的文件名中使用通配符和正则表达式。

regexuri 参数设置为 FALSE 时,将字符 "*" 和 "?" 视为通配符。当 regexuri 参数设置为 TRUE 时,字符 "*" 和 "?" 是指定正则表达式模式的一部分。

URI 中的文件名或子文件夹路径仅支持正则表达式模式,并且模式匹配与 REGEXP_LIKE 函数执行的模式匹配相同。目录名称不支持正则表达式模式。

对于外部表,仅对象存储中对文件创建的表支持此选项。

例如:

format => JSON_OBJECT('regexuri' value TRUE)

有关 REGEXP_LIKE 条件的详细信息,请参阅 Oracle Database 19c SQL Language ReferenceOracle Database 23ai SQL Language Reference 中的 REGEXP_LIKE Condition

regexuri: True

默认值:False

rejectlimit

在拒绝了指定数量的行后,操作将出错。

rejectlimit: number

默认值:0

removequotes

删除源文件中任何字段两端的引号。

removequotes: true

默认值:False

skipheaders

指定应从文件开头跳过多少行。

skipheaders: number

默认值:0(如果未指定),1(如果未指定值)

territory

指定地区名称以进一步确定输入数据特性。

territory: string

默认值:空值

有关 Oracle 支持的语言列表,请参阅 Oracle Database 19c Database Globalization Support Guide 中的 Locale DataOracle Database 23ai Database Globalization Support Guide

timestampformat

指定源文件中的时间戳格式。格式选项 AUTO 搜索以下格式:

YYYY-MM-DD HH:MI:SS.FF 
YYYY-MM-DD HH:MI:SS.FF3
YYYY-MM-DD HH24:MI:SS.FF3
MM/DD/YYYY HH:MI:SS.FF3

timestampformat: string

默认值:数据库时间戳格式

字符串中可以包含通配符字符,例如 "$"。

timestampltzformat

指定源文件中具有本地时区格式的时间戳。格式选项 AUTO 搜索以下格式:

DD Mon YYYY HH:MI:SS.FF TZR 
MM/DD/YYYY HH:MI:SS.FF TZR 
YYYY-MM-DD HH:MI:SS+/-TZR 
YYYY-MM-DD HH:MI:SS.FF3 
DD.MM.YYYY HH:MI:SS TZR

timestampltzformat: string

默认值:具有本地时区的数据库时间戳格式

timestamptzformat

指定源文件中具有时区格式的时间戳。格式选项 AUTO 搜索以下格式:

DD Mon YYYY HH:MI:SS.FF TZR 
MM/DD/YYYY HH:MI:SS.FF TZR 
YYYY-MM-DD HH:MI:SS+/-TZR 
YYYY-MM-DD HH:MI:SS.FF3 
DD.MM.YYYY HH:MI:SS TZR

timestamptzformat: string

默认值:带时区的数据库时间戳格式

trimspaces

指定如何截取字段中的前导空格和尾随空格。

请参阅 Oracle Database 19c UtilitiesOracle Database 23ai Utilitiestrim_spec 的说明。

trimspaces: rtrim| ltrim| notrim| lrtrim| ldrtrim

默认值:notrim

truncatecol

如果文件中的数据太长,无法放在一个字段中,则此选项将截断该字段的值,而不是拒绝行。

truncatecol:true

默认值:False

type

指定源文件类型。

请参阅 Oracle Database 19c UtilitiesOracle Database 23ai UtilitiesCSV 的说明。

如果 typedatapump,则唯一的另一个有效格式选项是 rejectlimit

如果 typedatapump,则仅支持 Oracle Cloud Infrastructure 对象存储和 Oracle Cloud Infrastructure Object Storage Classic

有关 typeavroorcparquet ,请参见 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet

对于 DBMS_CLOUD.COPY_COLLECTIONtype 的 JSON 数据,有两个有效值:json(默认值)和 ejson。对于 DBMS_CLOUD.COPY_COLLECTION ,这些值都指定输入为 JSON 数据。值 ejson 将导致文本 JSON 输入数据中的扩展对象转换为本机二进制 JSON 集合中的标量 JSON 值。值 json 不执行此转换,输入数据中的所有对象都将转换为二进制 JSON 格式。

对于 DBMS_CLOUD.COPY_DATAtype 的 JSON 数据,有一个有效值:json。此值指定输入为 JSON 数据。

type: csv|csv with embedded|csv without embedded |avro||datapump|orc|parquet

注意:

并非所有 DBMS_CLOUD 过程都支持所有这些类型。

csvcsv without embedded 相同。

默认值:空值

对于 JSON 数据,有两个用于 DBMS_CLOUD.COPY_COLLECTION 的有效 type 值:json|ejson 在这种情况下,默认值为 json。对于具有 DBMS_CLOUD.COPY_DATA 的 JSON 数据,只有 json 有效。

unpackarrays

仅与 COPY_COLLECTION 一起使用

设置为 true 时,如果加载的文档是数组,则数组的内容将作为文档加载,而不是数组本身。这仅适用于顶级数组。

设置为 true 时,整个数组将作为单个文档插入。

此选项仅对具有 DBMS_CLOUD.COPY_COLLECTION 的 JSON 收集数据有效。

unpackarrays: true

默认值:False