2 Data Pump Export

Data Pump Export Interfaces

You can interact with Data Pump Export by using a command line, a parameter file, or an interactive-command mode.

• Command-Line Interface: Enables you to specify most of the Export parameters directly on the command line. For a complete description of the parameters available in the command-line interface, see Parameters Available in Export's Command-Line Mode.

• Parameter File Interface: Enables you to specify command-line parameters in a parameter file. The only exception is the PARFILE parameter, because parameter files cannot be nested.

• Interactive-Command Interface: Stops logging to the terminal and displays the Export prompt, from which you can enter various commands, some of which are specific to interactive-command mode. This mode is enabled by pressing Ctrl+C during an export operation started with the command-line interface or the parameter file interface. Interactive-command mode is also enabled when you attach to an executing or stopped job.

  For a complete description of the commands available in interactive-command mode, see Commands Available in Export's Interactive-Command Mode.

Data Pump Export Modes

One of the most significant characteristics of an export operation is its mode, because the mode largely determines what is exported. Export provides different modes for unloading different portions of the database. The mode is specified on the command line, using the appropriate parameter. The available modes are as follows:

• Full Export Mode

• Schema Mode

• Table Mode

• Tablespace Mode

• Transportable Tablespace Mode

  
  

  See Also: Examples of Using Data Pump Export

  
  

Network Considerations

You can use SQL*Net connection strings or connection descriptors when you invoke the Data Pump Export utility. To do so, the listener must be running (lsnrctl start). The following example shows how to invoke Export using a SQL*Net connection:

expdp hr/hr@inst1 DIRECTORY=dpump_dir1 DUMPFILE=hr.dmp TABLES=employees

The hr/hr@inst1 results in a SQL*Net connection. The inst1 refers to a service name specified in the tnsnames.ora file. This means that the export client is being run remotely from the server to export the data to a dump file.

Do not confuse invoking the Export utility using a SQL*Net connection string with performing an export operation using the Export NETWORK_LINK command-line parameter.

The NETWORK_LINK parameter initiates a network export. This means that the expdp client initiates an export request, typically to the local server. That server contacts the remote database referenced by the database link in the NETWORK_LINK parameter, retrieves data from it, and writes the data to a dump file set back on the local system.

Data Filters

Data filters specify restrictions on the rows that are to be exported. These restrictions can be based on partition names and on the results of subqueries.

Each data filter can be specified once per table within a job. If different filters using the same name are applied to both a particular table and to the whole job, the filter parameter supplied for the specific table will take precedence.

Metadata Filters

Metadata filtering is implemented through the EXCLUDE and INCLUDE parameters. The EXCLUDE and INCLUDE parameters are mutually exclusive.

Metadata filters identify a set of objects to be included or excluded from an Export or Import operation. For example, you could request a full export, but without Package Specifications or Package Bodies.

To use filters correctly and to get the results you expect, remember that dependent objects of an identified object are processed along with the identified object. For example, if a filter specifies that an index is to be included in an operation, then statistics from that index will also be included. Likewise, if a table is excluded by a filter, then indexes, constraints, grants, and triggers upon the table will also be excluded by the filter.

If multiple filters are specified for an object type, an implicit AND operation is applied to them. That is, objects pertaining to the job must pass all of the filters applied to their object types.

The same metadata filter name can be specified multiple times within a job.

To see which objects can be filtered, you can perform queries on the following views: DATABASE_EXPORT_OBJECTS, SCHEMA_EXPORT_OBJECTS, and TABLE_EXPORT_OBJECTS. For example, you could perform the following query:

SQL> SELECT OBJECT_PATH, COMMENTS FROM SCHEMA_EXPORT_OBJECTS
  2  WHERE OBJECT_PATH LIKE '%GRANT';

The output of this query looks similar to the following:

OBJECT_PATH
--------------------------------------------------------------------------------
COMMENTS
--------------------------------------------------------------------------------
GRANT
Grants on objects in the selected schemas
 
OBJECT_GRANT
Grants on objects in the selected schemas
 
PROCDEPOBJ_GRANT
Grants on instance procedural objects in the selected schemas
 
 
OBJECT_PATH
--------------------------------------------------------------------------------
COMMENTS
--------------------------------------------------------------------------------
PROCOBJ_GRANT
Schema procedural object grants in the selected schemas
 
ROLE_GRANT
Role grants to users associated with the selected schemas
 
SYSTEM_GRANT
System privileges granted to users associated with the selected schemas
 
 
6 rows selected.

ATTACH

Default: job currently in the user's schema, if there is only one

Attaches the client session to an existing export job and automatically places you in the interactive-command interface. Export displays a description of the job to which you are attached and also displays the Export prompt.

ATTACH [=[schema_name.]job_name]

The schema_name is optional. To specify a schema other than your own, you must have the EXP_FULL_DATABASE role.

The job_name is optional if only one export job is associated with your schema and the job is active. To attach to a stopped job, you must supply the job name. To see a list of Data Pump job names, you can query the DBA_DATAPUMP_JOBS view or the USER_DATAPUMP_JOBS view.

When you are attached to the job, Export displays a description of the job and then displays the Export prompt.

When you specify the ATTACH parameter, you cannot specify any other parameters except for the connection string (user/password).

You cannot attach to a job in another schema unless it is already running.

The following is an example of using the ATTACH parameter. It assumes that the job, hr.export_job, already exists.

> expdp hr/hr ATTACH=hr.export_job

CONTENT

Default: ALL

Enables you to filter what Export unloads: data only, metadata only, or both.

CONTENT={ALL | DATA_ONLY | METADATA_ONLY}

• ALL unloads both data and metadata. This is the default.

• DATA_ONLY unloads only table row data; no database object definitions are unloaded.

• METADATA_ONLY unloads only database object definitions; no table row data is unloaded.

The following is an example of using the CONTENT parameter:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr.dmp CONTENT=METADATA_ONLY

This command will execute a schema-mode export that will unload only the metadata associated with the hr schema. It defaults to a schema-mode export of the hr schema because no export mode is specified.

DIRECTORY

Default: none for nonprivileged users; DATA_PUMP_DIR for privileged users

Specifies the location to which Export can write the dump file set and the log file.

DIRECTORY=directory_object

The directory_object is the name of a database directory object (not the name of an actual directory) that was previously created by the database administrator (DBA) using the SQL CREATE DIRECTORY command.

A directory object specified on the DUMPFILE or LOGFILE parameter overrides any directory object that you specify for the DIRECTORY parameter.

The following is an example of using the DIRECTORY parameter:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=employees.dmp CONTENT=METADATA_ONLY

The dump file, employees.dmp, will be written to the path that is associated with the directory object dpump_dir1.

The following is an example of using the default DATA_PUMP_DIR directory object available to privileged users. This example assumes that the EXP_FULL_DATABASE and IMP_FULL_DATABASE roles have been granted to the user hr. After the DATA_PUMP_DIR directory object has been created, a privileged user need not use the DIRECTORY parameter. Dump files, log files, and SQL files will be written to the path associated with DATA_PUMP_DIR.

SQL> CREATE DIRECTORY data_pump_dir AS '/usr/dba/dpumpfiles':

> expdp hr/hr DUMPFILE=emp.dmp LOGFILE=emp.log TABLES=hr.employees

The emp.dmp and emp.log files will be written to /usr/dba/dpumpfiles.

If the DATA_PUMP_DIR directory object had not first been created by a DBA, then the following error messages would have been displayed:

ORA-39002: invalid operation 
ORA-39070: Unable to open the log file. 
ORA-39087: directory name DATA_PUMP_DIR is invalid 

Remember that the default DATA_PUMP_DIR directory object is not available to nonprivileged users. In the following example, user sh is a nonprivileged user. Therefore, because no directory object is specified, error messages are generated and the export is not performed.

> expdp sh/sh DUMPFILE=sales.dmp LOGFILE=sales.log TABLES=sh.sales 
 
ORA-39002: invalid operation 
ORA-39070: Unable to open the log file. 
ORA-39145: directory object parameter must be specified and non-null

DUMPFILE

Default: expdat.dmp

Specifies the names, and optionally, the directory objects of dump files for an export job.

DUMPFILE=[directory_object:]file_name [, ...]

The directory_object is optional if one has already been established by the DIRECTORY parameter. If you supply a value here, it must be a directory object that already exists. A database directory object that is specified as part of the DUMPFILE parameter overrides a value specified by the DIRECTORY parameter.

You can supply multiple file_name specifications as a comma-delimited list or in separate DUMPFILE parameter specifications. If no extension is given for the filename, then Export uses the default file extension of .dmp. The filenames can contain a substitution variable (%U), which implies that multiple files may be generated. The substitution variable is expanded in the resulting filenames into a 2-digit, fixed-width, incrementing integer starting at 01 and ending at 99. If a file specification contains two substitution variables, both are incremented at the same time. For example, exp%Uaa%U.dmp would resolve to exp01aa01.dmp, exp02aa02.dmp, and so forth.

If the FILESIZE parameter is specified, each dump file will have a maximum of that size in bytes and be nonextensible. If more space is required for the dump file set and a template with a substitution variable (%U) was supplied, a new dump file is automatically created of the size specified by FILESIZE, if there is room on the device.

If templates with a substitution variable (%U) were specified along with the PARALLEL parameter, then one file for each template is initially created. More files are created from the templates as they are needed based on how much data is being exported and how many parallel processes are given work to perform during the job.

As each file specification or file template containing a substitution variable is defined, it is instantiated into one fully qualified filename and Export attempts to create it. The file specifications are processed in the order in which they are specified. If the job needs extra files because the maximum file size is reached, or to keep parallel workers active, then additional files are created if file templates with substitution variables were specified.

If there are preexisting files that match the resulting filenames, an error is generated. The existing dump files will not be overwritten.

The following is an example of using the DUMPFILE parameter:

> expdp hr/hr SCHEMAS=hr DIRECTORY=dpump_dir1 DUMPFILE=dpump_dir2:exp1.dmp,
 exp2%U.dmp PARALLEL=3

The dump file, exp1.dmp, will be written to the path associated with the directory object dpump_dir2 because dpump_dir2 was specified as part of the dump file name, and therefore overrides the directory object specified with the DIRECTORY parameter. Because all three parallel processes will be given work to perform during this job, the exp201.dmp and exp202.dmp dump files will be created and they will be written to the path associated with the directory object, dpump_dir1, that was specified with the DIRECTORY parameter.

ESTIMATE

Default: BLOCKS

Specifies the method that Export will use to estimate how much disk space each table in the export job will consume (in bytes). The estimate is printed in the log file and displayed on the client's standard output device. The estimate is for table row data only; it does not include metadata.

ESTIMATE={BLOCKS | STATISTICS}

• BLOCKS - The estimate is calculated by multiplying the number of database blocks used by the target objects times the appropriate block sizes.

• STATISTICS - The estimate is calculated using statistics for each table. For this method to be as accurate as possible, all tables should have been analyzed recently.

The following example shows a use of the ESTIMATE parameter in which the estimate is calculated using statistics for the employees table:

> expdp hr/hr TABLES=employees ESTIMATE=STATISTICS DIRECTORY=dpump_dir1
 DUMPFILE=estimate_stat.dmp

ESTIMATE_ONLY

Default: n

Instructs Export to estimate the space that a job would consume, without actually performing the export operation.

ESTIMATE_ONLY={y | n}

If ESTIMATE_ONLY=y, then Export estimates the space that would be consumed, but quits without actually performing the export operation.

The following shows an example of using the ESTIMATE_ONLY parameter to determine how much space an export of the HR schema will take.

> expdp hr/hr ESTIMATE_ONLY=y NOLOGFILE=y

EXCLUDE

Default: none

Enables you to filter the metadata that is exported by specifying objects and object types that you want excluded from the export operation.

EXCLUDE=object_type[:name_clause] [, ...]

All object types for the given mode of export will be included except those specified in an EXCLUDE statement. If an object is excluded, all of its dependent objects are also excluded. For example, excluding a table will also exclude all indexes and triggers on the table.

The name_clause is optional. It allows selection of specific objects within an object type. It is a SQL expression used as a filter on the type's object names. It consists of a SQL operator and the values against which the object names of the specified type are to be compared. The name clause applies only to object types whose instances have names (for example, it is applicable to TABLE, but not to GRANT). The name clause must be separated from the object type with a colon and enclosed in double quotation marks, because single-quotation marks are required to delimit the name strings. For example, you could set EXCLUDE=INDEX:"LIKE 'EMP%'" to exclude all indexes whose names start with emp. This is shown in the following example:

> expdp hr/hr EXCLUDE=INDEX:\"LIKE \'EMP%\'\" DUMPFILE=dpump_dir1:exp.dmp
NOLOGFILE=y

If no name_clause is provided, all objects of the specified type are excluded.

More than one EXCLUDE statement can be specified.

Oracle recommends that you place EXCLUDE clauses in a parameter file to avoid having to use escape characters on the command line. This example shows how the use of the backslash escape character would be necessary if you specified this EXCLUDE clause on the command line, rather than in a parameter file.

If the object_type you specify is CONSTRAINT, GRANT, or USER, you should be aware of the effects this will have, as described in the following paragraphs.

The following constraints cannot be excluded:

• NOT NULL constraints

• Constraints needed for the table to be created and loaded successfully; for example, primary key constraints for index-organized tables, or REF SCOPE and WITH ROWID constraints for tables with REF columns

This means that the following EXCLUDE statements will be interpreted as follows:

• EXCLUDE=CONSTRAINT will exclude all (nonreferential) constraints, except for NOT NULL constraints and any constraints needed for successful table creation and loading.

• EXCLUDE=REF_CONSTRAINT will exclude referential integrity (foreign key) constraints.

Specifying EXCLUDE=GRANT excludes object grants on all object types and system privilege grants.

Specifying EXCLUDE=USER excludes only the definitions of users, not the objects contained within users' schemas.

To exclude a specific user and all objects of that user, specify a filter such as the following (where hr is the schema name of the user you want to exclude):

EXCLUDE=SCHEMA:"='HR'"

If you try to exclude a user by using a statement such as EXCLUDE=USER:"='HR'", then only CREATE USER hr DDL statements will be excluded, and you may not get the results you expect.

The EXCLUDE and INCLUDE parameters are mutually exclusive.

Neither EXCLUDE nor INCLUDE can be used if the CONTENT=DATA_ONLY parameter is specified, because that implies export of table row data only.

The following is an example of using the EXCLUDE statement.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr_exclude.dmp EXCLUDE=VIEW,
PACKAGE, FUNCTION

This will result in a schema-mode export in which all of the hr schema will be exported except its views, packages, and functions.

FILESIZE

Default: 0 (unlimited)

Specifies the maximum size of each export dump file. If the size is reached for any member of the dump file set, that file is closed and an attempt is made to create a new file, if the file specification contains a substitution variable. If there is insufficient space on the device to write a file of the specified size, the export operation will stop. It can be restarted after the situation is corrected.

FILESIZE=integer[B | K | M | G]

The integer can be followed by B, K, M, or G (indicating bytes, kilobytes, megabytes, and gigabytes respectively). Bytes is the default. The actual size of the resulting file may be rounded down slightly to match the size of the internal blocks used in dump files.

The minimum size for a file is ten times the default Data Pump block size, which is 4 kilobytes.

The following shows an example in which the size of the dump file is set to 3 megabytes:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr_3m.dmp FILESIZE=3M

FLASHBACK_SCN

Default: none

Specifies the system change number (SCN) that Export will use to enable the Flashback utility. The export operation is performed with data that is consistent as of this SCN. If the NETWORK_LINK parameter is specified, the SCN refers to the SCN of the source database.

FLASHBACK_SCN=scn_value

FLASHBACK_SCN and FLASHBACK_TIME are mutually exclusive.

The following example assumes that an existing SCN value of 384632 exists. It exports the hr schema up to SCN 384632.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr_scn.dmp FLASHBACK_SCN=384632

FLASHBACK_TIME

Default: none

The SCN that most closely matches the specified time is found, and this SCN is used to enable the Flashback utility. The export operation is performed with data that is consistent as of this SCN.

FLASHBACK_TIME="TO_TIMESTAMP(time-value)"

FLASHBACK_TIME and FLASHBACK_SCN are mutually exclusive.

You can specify the time in any format that the DBMS_FLASHBACK.ENABLE_AT_TIME procedure accepts, for example:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr_time.dmp
FLASHBACK_TIME="TO_TIMESTAMP('25-08-2003 14:35:00', 'DD-MM-YYYY HH24:MI:SS')"

This example may require the use of escape characters, depending on your operating system. See Command-Line Escape Characters Used in Examples.

FULL

Default: n

Specifies that you want to perform a full database mode export.

FULL={y | n}

If FULL=y, all data and metadata are exported.

To perform a full export, you must have the EXP_FULL_DATABASE role.

The following system schemas are not exported as part of a Full export because the metadata they contain is exported as part of other objects in the dump file set: SYS, ORDSYS, ORDPLUGINS, CTXSYS, MDSYS, LBACSYS, and XDB. Also excluded are any tables that are registered in the SYS.KU_NOEXP_TAB dictionary table.

The following is an example of using the FULL parameter. The dump file, expfull.dmp is written to the dpump_dir2 directory.

> expdp hr/hr DIRECTORY=dpump_dir2 DUMPFILE=expfull.dmp FULL=y NOLOGFILE=y

HELP

Default: N

Displays online help for the Export utility.

HELP = {y | n}

If HELP=y is specified, Export displays a summary of all Export command-line parameters and interactive commands.

> expdp HELP = y

This example will display a brief description of all Export parameters and commands.

INCLUDE

Default: none

Enables you to filter the metadata that is exported by specifying objects and object types for the current export mode. The specified objects and all their dependent objects are exported. Grants on these objects are also exported.

INCLUDE = object_type[:name_clause] [, ...]

Only object types explicitly specified in INCLUDE statements are exported. No other object types, including the schema definition information that is normally part of a schema-mode export when you have the EXP_FULL_DATABASE role, are exported.

To see a list of valid object type path names for use with the INCLUDE parameter, you can query the following views: DATABASE_EXPORT_OBJECTS, SCHEMA_EXPORT_OBJECTS, and TABLE_EXPORT_OBJECTS.

The name_clause is optional. It allows fine-grained selection of specific objects within an object type. It is a SQL expression used as a filter on the object names of the type. It consists of a SQL operator and the values against which the object names of the specified type are to be compared. The name clause applies only to object types whose instances have names (for example, it is applicable to TABLE, but not to GRANT). The optional name clause must be separated from the object type with a colon and enclosed in double quotation marks, because single-quotation marks are required to delimit the name strings.

Oracle recommends that INCLUDE statements be placed in a parameter file so that you can avoid having to use operating system-specific escape characters on the command line. For example, suppose you have a parameter file named hr.par with the following content:

SCHEMAS=HR
DUMPFILE=expinclude.dmp
DIRECTORY=dpump_dir1
LOGFILE=expinclude.log
INCLUDE=TABLE:"IN ('EMPLOYEES', 'DEPARTMENTS')"
INCLUDE=PROCEDURE
INCLUDE=INDEX:"LIKE 'EMP%'"

You could then use the hr.par file to start an export operation, without having to enter any other parameters on the command line:

> expdp hr/hr parfile=hr.par

The INCLUDE and EXCLUDE parameters are mutually exclusive. Additionally, neither one can be used if the CONTENT=DATA_ONLY parameter is specified, because that implies export of table rows only.

The following example performs an export of all tables (and their dependent objects) in the hr schema:

> expdp hr/hr INCLUDE=TABLE DUMPFILE=dpump_dir1:exp_inc.dmp NOLOGFILE=y

JOB_NAME

Default: system-generated name of the form SYS_<operation>_<mode>_NN

Specifies a name for the export job. The job name is used to identify the export job in subsequent actions, such as when the ATTACH parameter is used to attach to a job. The job name becomes the name of the master table in the current user's schema. The master table is used to control the export job.

JOB_NAME=jobname_string

The jobname_string specifies a name of up to 30 bytes for this export job. The bytes must represent printable characters and spaces. If spaces are included, the name must be enclosed in single quotation marks (for example, 'Thursday Export'). The job name is implicitly qualified by the schema of the user performing the export operation.

The default job name is system-generated in the form SYS_<operation>_<mode>_NN, where NN expands to a 2-digit incrementing integer starting at 01. An example of a default name is 'SYS_EXPORT_TABLESPACE_02'.

The following example shows an export operation that is assigned a job name of exp_job:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=exp_job.dmp JOB_NAME='exp_job'
NOLOGFILE=y

LOGFILE

Default: export.log

Specifies the name, and optionally, a directory, for the log file of the export job.

LOGFILE=[directory_object:]file_name

You can specify a database directory_object previously established by the DBA. This overrides the directory object specified with the DIRECTORY parameter.

The file_name specifies a name for the log file. The default behavior is to create a file named export.log in the directory referenced by the directory object specified in the DIRECTORY parameter.

All messages regarding work in progress, work completed, and errors encountered are written to the log file. (For a real-time status of the job, use the STATUS command in interactive mode.)

A log file is always created for an export job unless the NOLOGFILE parameter is specified. As with the dump file set, the log file is relative to the server and not the client.

An existing file matching the filename will be overwritten.

The following example shows how to specify a log file name if you do not want to use the default:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr.dmp LOGFILE=hr_export.log

NETWORK_LINK

Default: none

Enables a network export when you specify the name of a valid database link. A network export moves data from a remote database to a dump file set local to the instance running the Data Pump job.

NETWORK_LINK=source_database_link

The NETWORK_LINK parameter initiates a network export. This means that the expdp client initiates an export request, typically to the local server. That server contacts the remote database referenced by the source_database_link, retrieves data from it, and writes the data to a dump file set back on the local system.

The source_database_link provided must be the name of a database link to a source system. If the database does not already have a database link, you or your DBA must create one. The following information is required: host machine name, and port number and SID for the database. For more information about the CREATE DATABASE LINK statement, see Oracle Database SQL Reference.

If the source database is read-only, then the user on the source database must have a locally managed tablespace assigned as the default temporary tablespace. Otherwise, the job will fail. For further details about this, see the information about creating locally managed temporary tablespaces in the Oracle Database Administrator's Guide.

Tables with columns that are object types are not supported in a network export. An ORA-22804 error will be generated and the export will move on to the next table. To work around this restriction, you can manually create the dependent object types within the database from which the export is being run.

The following is an example of using the NETWORK_LINK parameter. The source_database_link would be replaced with the name of a valid database link that must already exist.

> expdp hr/hr DIRECTORY=dpump_dir1 NETWORK_LINK=source_database_link
  DUMPFILE=network_export.dmp LOGFILE=network_export.log

NOLOGFILE

Default: n

Specifies whether to suppress creation of a log file.

NOLOGFILE={y | n}

Specify NOLOGFILE=y to suppress the default behavior of creating a log file. Progress and error information is still written to the standard output device of any attached clients, including the client that started the original export operation. If there are no clients attached to a running job and you specify NOLOGFILE=y, you run the risk of losing important progress and error information.

The following is an example of using the NOLOGFILE parameter:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=hr.dmp NOLOGFILE=y

This command results in a schema-mode export in which no log file is written.

PARALLEL

Default: 1

Specifies the maximum number of threads of active execution operating on behalf of the export job. This execution set consists of a combination of worker processes and parallel I/O server processes. The master control process and worker processes acting as query coordinators in parallel query operations do not count toward this total.

This parameter enables you to make trade-offs between resource consumption and elapsed time.

PARALLEL=integer

The value you specify for integer should match the number of files in the dump file set (or you should specify substitution variables in the dump file specifications). Because each active worker process or I/O server process writes exclusively to one file at a time, an insufficient number of files can have adverse effects. Some of the worker processes will be idle while waiting for files, thereby degrading the overall performance of the job. More importantly, if any member of a cooperating group of parallel I/O server processes becomes idle, then the export operation will be stopped with an ORA-39095 error. Both situations can be corrected by attaching to the job using the Data Pump Export utility, adding more files using the ADD_FILE command while in interactive mode, and in the case of a stopped job, restarting the job.

To increase or decrease the value of PARALLEL during job execution, use interactive-command mode. Decreasing parallelism does not result in fewer worker processes associated with the job; it merely decreases the number of worker processes that will be executing at any given time. Also, any ongoing work must reach an orderly completion point before the decrease takes effect. Therefore, it may take a while to see any effect from decreasing the value. Idle workers are not deleted until the job exits.

Increasing the parallelism takes effect immediately if there is work that can be performed in parallel.

This parameter is valid only in the Enterprise Edition of Oracle Database 10g.

The following is an example of using the PARALLEL parameter:

> expdp hr/hr DIRECTORY=dpump_dir1 LOGFILE=parallel_export.log 
JOB_NAME=par3_job DUMPFILE=par_exp%u.dmp PARALLEL=3
 

This results in a schema-mode export of the hr schema in which up to three files could be created in the path pointed to by the directory object, dpump_dir1. As a result of the command in this example, the following dump files are created:

• par_exp01.dmp

• par_exp02.dmp

• par_exp03.dmp

• 
  

  See Also: DUMPFILE Commands Available in Export's Interactive-Command Mode Performing a Parallel Full Database Export

  
  

PARFILE

Default: none

Specifies the name of an export parameter file.

PARFILE=[directory_path]file_name

Unlike dump and log files, which are created and written by the Oracle database, the parameter file is opened and read by the client running the expdp image. Therefore, a directory object name is neither required nor appropriate. The directory path is an operating system-specific directory specification. The default is the user's current directory.

The PARFILE parameter cannot be specified within a parameter file.

The content of an example parameter file, hr.par, might be as follows:

SCHEMAS=HR
DUMPFILE=exp.dmp
DIRECTORY=dpump_dir1
LOGFILE=exp.log

You could then issue the following Export command to specify the parameter file:

> expdp hr/hr parfile=hr.par

QUERY

Default: none

Enables you to filter the data that is exported by specifying a clause for a SQL SELECT statement, which is applied to all tables in the export job or to a specific table.

QUERY = [schema.][table_name:] query_clause

The query_clause is typically a WHERE clause for fine-grained row selection, but could be any SQL clause. For example, an ORDER BY clause could be used to speed up a migration from a heap-organized table to an index-organized table. If a [schema.]table_name is not supplied, the query is applied to (and must be valid for) all tables in the export job. A table-specific query overrides a query applied to all tables.

When the query is to be applied to a specific table, a colon must separate the table name from the query clause. More than one table-specific query can be specified, but only one can be specified per table. Oracle highly recommends that you place QUERY specifications in a parameter file so that you can avoid having to use operating system-specific escape characters on the command line.

The query must be enclosed in single or double quotation marks.

When the QUERY parameter is used, the external tables method (rather than the direct path method) is used for data access.

To specify a schema other than your own in a table-specific query, you need the EXP_FULL_DATABASE role.

The QUERY parameter cannot be used in conjunction with the following parameters:

• CONTENT=METADATA_ONLY

• ESTIMATE_ONLY

• TRANSPORT_TABLESPACES

The following is an example of using the QUERY parameter:

> expdp hr/hr QUERY=employees:'"WHERE department_id > 10 AND salary > 10000"'
NOLOGFILE=y DIRECTORY=dpump_dir1 DUMPFILE=exp1.dmp 

This example unloads all tables in the hr schema, but only the rows that fit the query expression. In this case, all rows in all tables (except employees) in the hr schema will be unloaded. For the employees table, only rows that meet the query criteria are unloaded.

SCHEMAS

Default: current user's schema

Specifies that you want to perform a schema-mode export. This is the default mode for Export.

SCHEMAS=schema_name [, ...]

If you have the EXP_FULL_DATABASE role, then you can specify a single schema other than your own or a list of schema names. The EXP_FULL_DATABASE role also allows you to export additional nonschema object information for each specified schema so that the schemas can be re-created at import time. This additional information includes the user definitions themselves and all associated system and role grants, user password history, and so on.

If no mode is specified, all objects in the current user's schema are exported.

If you do not have the EXP_FULL_DATABASE role, then you can specify only your own schema.

Any tables that are registered in the SYS.KU_NOEXP_TAB dictionary table are excluded in schema mode.

The following is an example of using the SCHEMAS parameter. Note that user hr is allowed to specify more than one schema because the EXP_FULL_DATABASE role was previously assigned to it for the purpose of these examples.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=expdat.dmp SCHEMAS=hr,sh,oe 
 

This results in a schema-mode export in which the schemas, hr, sh, and oe will be written to the expdat.dmp dump file located in the dpump_dir1 directory.

STATUS

Default: 0

Displays detailed status of the job, along with a description of the current operation. An estimated completion percentage for the job is also returned

STATUS=[integer]

If you supply a value for integer, it specifies how frequently, in seconds, job status should be displayed in logging mode. If no value is entered or if the default value of 0 is used, information is displayed only upon completion of each object type, table, or partition.

This status information is written only to your standard output device, not to the log file (if one is in effect).

The following is an example of using the STATUS parameter.

> expdp hr/hr DIRECTORY=dpump_dir1 SCHEMAS=hr,sh STATUS=300

This example will export the hr and sh schemas and display the status of the export every 5 minutes (60 seconds x 5 = 300 seconds).

TABLES

Default: none

Specifies that you want to perform a table-mode export.

TABLES=[schema_name.]table_name[:partition_name] [, ...]

You can filter the data and metadata that is exported, by specifying a comma-delimited list of tables and partitions or subpartitions. If a partition name is specified, it must be the name of a partition or subpartition in the associated table. Only the specified set of tables, partitions, and their dependent objects are unloaded.

The table name that you specify can be preceded by a qualifying schema name. All table names specified must reside in the same schema. The schema defaults to that of the current user. To specify a schema other than your own, you must have the EXP_FULL_DATABASE role.

The use of wildcards is supported for one table name per export operation. For example, TABLES=emp% would export all tables having names that start with 'EMP.'

Cross-schema references are not exported. For example, a trigger defined on a table within one of the specified schemas, but that resides in a schema not explicitly specified, is not exported.

Types used by the table are not exported in table mode. This means that if you subsequently import the dump file and the TYPE does not already exist in the destination database, the table creation will fail.

The use of synonyms as values for the TABLES parameter is not supported. For example, if the regions table in the hr schema had a synonym of regn, it would not be valid to use TABLES=regn. An error would be returned.

The export of partitions is not supported over network links.

The export of tables that include wildcards in the table name is not supported if the table has partitions.

The following example shows a simple use of the TABLES parameter to export three tables found in the hr schema: employees, jobs, and departments. Because user hr is exporting tables found in the hr schema, the schema name is not needed before the table names.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=tables.dmp TABLES=employees,jobs,departments

The following example shows the use of the TABLES parameter to export partitions:

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=tables_part.dmp TABLES=sh.sales:sales_Q1_2000,sh.sales:sales_Q2_2000

This example exports the partitions, sales_Q1_2000 and sales_Q2_2000, from the table sales in the schema sh.

TABLESPACES

Default: none

Specifies a list of tablespace names to be exported in tablespace mode.

TABLESPACES=tablespace_name [, ...]

In tablespace mode, only the tables contained in a specified set of tablespaces are unloaded. If a table is unloaded, its dependent objects are also unloaded. If any part of a table resides in the specified set, then that table and all of its dependent objects are exported.

The following is an example of using the TABLESPACES parameter. The example assumes that tablespaces tbs_4, tbs_5, and tbs_6 already exist.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=tbs.dmp 
TABLESPACES=tbs_4, tbs_5, tbs_6

This results in a tablespace export in which objects (and their dependent objects) from the specified tablespaces (tbs_4, tbs_5, and tbs_6) will be unloaded.

TRANSPORT_FULL_CHECK

Default: n

Specifies whether or not to check for dependencies between those objects inside the transportable set and those outside the transportable set. This parameter is applicable only to a transportable-tablespace mode export.

TRANSPORT_FULL_CHECK={y | n}

If TRANSPORT_FULL_CHECK=y, then Export verifies that there are no dependencies between those objects inside the transportable set and those outside the transportable set. The check addresses two-way dependencies. For example, if a table is inside the transportable set but its index is not, a failure is returned and the export operation is terminated. Similarly, a failure is also returned if an index is in the transportable set but the table is not.

If TRANSPORT_FULL_CHECK=n, then Export verifies only that there are no objects within the transportable set that are dependent on objects outside the transportable set. This check addresses a one-way dependency. For example, a table is not dependent on an index, but an index is dependent on a table, because an index without a table has no meaning. Therefore, if the transportable set contains a table, but not its index, then this check succeeds. However, if the transportable set contains an index, but not the table, the export operation is terminated.

In addition to this check, Export always verifies that all storage segments of all tables (and their indexes) defined within the tablespace set specified by TRANSPORT_TABLESPACES are actually contained within the tablespace set.

The following is an example of using the TRANSPORT_FULL_CHECK parameter. It assumes that tablespace tbs_1 exists.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=tts.dmp 
TRANSPORT_TABLESPACES=tbs_1 TRANSPORT_FULL_CHECK=y LOGFILE=tts.log 

TRANSPORT_TABLESPACES

Default: none

Specifies that you want to perform a transportable-tablespace-mode export.

TRANSPORT_TABLESPACES=tablespace_name [, ...]

Use the TRANSPORT_TABLESPACES parameter to specify a list of tablespace names for which object metadata will be exported from the source database into the target database.

Transportable jobs are not restartable.

Transportable jobs are restricted to a degree of parallelism of 1.

Transportable tablespace mode requires that you have the EXP_FULL_DATABASE role.

The following is an example of using the TRANSPORT_TABLESPACES parameter. It assumes that tablespace tbs_1 exists.

> expdp hr/hr DIRECTORY=dpump_dir1 DUMPFILE=tts.dmp
TRANSPORT_TABLESPACES=tbs_1 TRANSPORT_FULL_CHECK=y LOGFILE=tts.log

VERSION

Default: COMPATIBLE

Specifies the version of database objects to be exported. This can be used to create a dump file set that is compatible with a previous release of Oracle Database.

VERSION={COMPATIBLE | LATEST | version_string}

The legal values for the VERSION parameter are as follows:

• COMPATIBLE - This is the default value. The version of the metadata corresponds to the database compatibility level. Database compatibility must be set to 9.2 or higher.

• LATEST - The version of the metadata corresponds to the database version.

• version_string - A specific database version (for example, 10.0.0). In Oracle Database 10g, this value cannot be lower than 9.2.

Database objects or attributes that are incompatible with the specified version will not be exported. For example, tables containing new datatypes that are not supported in the specified version will not be exported.

The following example shows an export for which the version of the metadata will correspond to the database version:

> expdp hr/hr TABLES=hr.employees VERSION=LATEST DIRECTORY=dpump_dir1
DUMPFILE=emp.dmp NOLOGFILE=y

ADD_FILE

Adds additional files or wildcard file templates to the export dump file set.

ADD_FILE=[directory_object]file_name [,...]

The file_name must not contain any directory path information. However, it can include a substitution variable, %U, which indicates that multiple files may be generated using the specified filename as a template. It can also specify another directory_object.

The size of the file being added is determined by the setting of the FILESIZE parameter.

The following example adds two dump files to the dump file set. A directory object is not specified for the dump file named hr2.dmp so the default directory object of dpump_dir1 is assumed. A different directory object, dpump_dir2, is specified for the dump file named hr3.dmp.

expdp> ADD_FILE=hr2.dmp, dpump_dir2:hr3.dmp

CONTINUE_CLIENT

Changes the Export mode from interactive-command mode to logging mode.

CONTINUE_CLIENT

In logging mode, status is continually output to the terminal. If the job is currently stopped, then CONTINUE_CLIENT will also cause the client to attempt to start the job.

expdp> CONTINUE_CLIENT

EXIT_CLIENT

Stops the export client session, exits Export, and discontinues logging to the terminal, but leaves the current job running.

EXIT_CLIENT

Because EXIT_CLIENT stops the client session but leaves the job running, you can attach to the job at a later time. To see the status of the job, you can monitor the log file for the job or you can query the USER_DATAPUMP_JOBS view or the V$SESSION_LONGOPS view.

expdp> EXIT_CLIENT

HELP

Provides information about Data Pump Export commands available in interactive-command mode.

HELP

Displays information about the commands available in interactive-command mode.

expdp> HELP

KILL_JOB

Detaches all currently attached client sessions and then kills the current job. It exits Export and returns to the terminal prompt.

KILL_JOB

A job that is killed using KILL_JOB cannot be restarted. All attached clients, including the one issuing the KILL_JOB command, receive a warning that the job is being killed by the current user and are then detached. After all clients are detached, the job's process structure is immediately run down and the master table and dump files are deleted. Log files are not deleted.

expdp> KILL_JOB

PARALLEL

Enables you to increase or decrease the number of active worker processes for the current job.

PARALLEL=integer

PARALLEL is available as both a command-line parameter and an interactive-command mode parameter. You set it to the desired number of parallel processes. An increase takes effect immediately if there are sufficient files and resources. A decrease does not take effect until an existing process finishes its current task. If the value is decreased, workers are idled but not deleted until the job exits.

PARALLEL=10

START_JOB

Starts the current job to which you are attached.

START_JOB

The START_JOB command restarts the current job to which you are attached (the job cannot be currently executing). The job is restarted with no data loss or corruption after an unexpected failure or after you issued a STOP_JOB command, provided the dump file set and master table remain undisturbed.

Transportable-tablespace-mode exports are not restartable.

expdp> START_JOB

STATUS

Displays cumulative status of the job, along with a description of the current operation. An estimated completion percentage for the job is also returned.

STATUS[=integer]

You have the option of specifying how frequently, in seconds, this status should be displayed in logging mode. If no value is entered or if the default value of 0 is used, the periodic status display is turned off and status is displayed only once.

This status information is written only to your standard output device, not to the log file (even if one is in effect).

The following example will display the status every five minutes (300 seconds):

STATUS=300

STOP_JOB

Stops the current job either immediately or after an orderly shutdown, and exits Export.

STOP_JOB[=IMMEDIATE]

If the master table and dump file set are not disturbed when or after the STOP_JOB command is issued, the job can be attached to and restarted at a later time with the START_JOB command.

To perform an orderly shutdown, use STOP_JOB (without any associated value). A warning requiring confirmation will be issued. An orderly shutdown stops the job after worker processes have finished their current tasks.

To perform an immediate shutdown, specify STOP_JOB=IMMEDIATE. A warning requiring confirmation will be issued. All attached clients, including the one issuing the STOP_JOB command, receive a warning that the job is being stopped by the current user and they will be detached. After all clients are detached, the process structure of the job is immediately run down. That is, the master process will not wait for the worker processes to finish their current tasks. There is no risk of corruption or data loss when you specify STOP_JOB=IMMEDIATE. However, some tasks that were incomplete at the time of shutdown may have to be redone at restart time.

expdp> STOP_JOB=IMMEDIATE

Performing a Table-Mode Export

Example 2-1 shows a table-mode export, specified using the TABLES parameter. Issue the following Data Pump export command to perform a table export of the tables employees and jobs from the human resources (hr) schema:

expdp hr/hr TABLES=employees,jobs DUMPFILE=dpump_dir1:table.dmp NOLOGFILE=y

Because user hr is exporting tables in his own schema, it is not necessary to specify the schema name for the tables. The NOLOGFILE=y parameter indicates that an Export log file of the operation will not be generated.

Data-Only Unload of Selected Tables and Rows

Example 2-2 shows the contents of a parameter file (exp.par) that you could use to perform a data-only unload of all tables in the human resources (hr) schema except for the tables countries, locations, and regions. All rows in the employees table are unloaded except those with a department_id not equal to 50. The rows are ordered by employee_id.

DIRECTORY=dpump_dir1
DUMPFILE=dataonly.dmp
CONTENT=DATA_ONLY
EXCLUDE=TABLE:"IN ('COUNTRIES', 'LOCATIONS', 'REGIONS')"
QUERY=employees:"WHERE department_id !=50 ORDER BY employee_id"

You can issue the following command to execute the exp.par parameter file:

> expdp hr/hr PARFILE=exp.par

A schema-mode export (the default mode) is performed, but the CONTENT parameter effectively limits the export to an unload of just the tables. The DBA previously created the directory object dpump_dir1 which points to the directory on the server where user hr is authorized to read and write export dump files. The dump file dataonly.dmp is created in dpump_dir1.

Estimating Disk Space Needed in a Table-Mode Export

Example 2-3 shows the use of the ESTIMATE_ONLY parameter to estimate the space that would be consumed in a table-mode export, without actually performing the export operation. Issue the following command to use the BLOCKS method to estimate the number of bytes required to export the data in the following three tables located in the human resource (hr) schema: employees, departments, and locations.

> expdp hr/hr DIRECTORY=dpump_dir1 ESTIMATE_ONLY=y TABLES=employees, 
departments, locations LOGFILE=estimate.log

The estimate is printed in the log file and displayed on the client's standard output device. The estimate is for table row data only; it does not include metadata.

Performing a Schema-Mode Export

Example 2-4 shows a schema-mode export of the hr schema. In a schema-mode export, only objects belonging to the corresponding schemas are unloaded. Because schema mode is the default mode, it is not necessary to specify the SCHEMAS parameter on the command line, unless you are specifying more than one schema or a schema other than your own.

> expdp hr/hr DUMPFILE=dpump_dir1:expschema.dmp LOGFILE=dpump_dir1:expschema.log

Performing a Parallel Full Database Export

Example 2-5 shows a full database Export that will have 3 parallel worker processes.

> expdp hr/hr FULL=y DUMPFILE=dpump_dir1:full1%U.dmp, dpump_dir2:full2%U.dmp
FILESIZE=2G PARALLEL=3 LOGFILE=dpump_dir1:expfull.log JOB_NAME=expfull

Using Interactive Mode to Stop and Reattach to a Job

To start this example, reexecute the parallel full export in Example 2-5. While the export is running, press Ctrl+C. This will start the interactive-command interface of Data Pump Export. In the interactive interface, logging to the terminal stops and the Export prompt is displayed.

Issue the following command to stop the job:

Export> STOP_JOB=IMMEDIATE
Are you sure you wish to stop this job ([y]/n): y

The job is placed in a stopped state and exits the client. Example 2-6 shows how to reattach to the job.

> expdp hr/hr ATTACH=EXPFULL

After the job status is displayed, you can issue the CONTINUE_CLIENT command to resume logging mode and restart the expfull job.

Export> CONTINUE_CLIENT

A message is displayed that the job has been reopened, and processing status is output to the client.