Skip to main content

What is Smuggler

C#JavaNode.js

ForDatabase​

By default, DocumentStore.Smuggler works on the database set in the DocumentStore.Database property.
To run Smuggler against a different database, switch to it with the ForDatabase method.

var northwindSmuggler = store
    .Smuggler
    .ForDatabase("Northwind");

Export​

Export writes the selected data to a .ravendbdump file, or streams it directly into another database.
Use DatabaseSmugglerExportOptions to choose what to include.

Example: export indexes and documents to a file​

// export only Indexes and Documents to a given file
var exportOperation = await store
    .Smuggler
    .ExportAsync(
        new DatabaseSmugglerExportOptions
        {
            OperateOnTypes = DatabaseItemType.Indexes
                             | DatabaseItemType.Documents
        },
        @"C:\ravendb-exports\Northwind.ravendbdump",
        token);

await exportOperation.WaitForCompletionAsync();

Export specific collections​

By default, all collections are exported.
To export only specific collections, list their names in the Collections option.

// Export only the "Orders" and "Categories" collections to a file
var exportOperation = await store
    .Smuggler
    .ExportAsync(
        new DatabaseSmugglerExportOptions
        {
            Collections = new List<string> { "Orders", "Categories" }
        },
        @"C:\ravendb-exports\Northwind.ravendbdump",
        token);

await exportOperation.WaitForCompletionAsync();

See ExportAsync and DatabaseSmugglerExportOptions in the Syntax section.

Import​

Import reads data from a .ravendbdump file or a stream and writes it into the database.
Use DatabaseSmugglerImportOptions to choose what to include.

Example: import documents from a file​

// import only Documents from a given file
var importOperation = await store
    .Smuggler
    .ImportAsync(
        new DatabaseSmugglerImportOptions
        {
            OperateOnTypes = DatabaseItemType.Documents
        },
        // import the .ravendbdump file that you exported (i.e. in the export example above)
        @"C:\ravendb-exports\Northwind.ravendbdump",
        token);

await importOperation.WaitForCompletionAsync();

Import specific collections​

By default, all collections are imported.
To import only specific collections, list their names in the Collections option.

// Import only the "Orders" and "Categories" collections from the file
var importOperation = await store
    .Smuggler
    .ImportAsync(
        new DatabaseSmugglerImportOptions
        {
            Collections = new List<string> { "Orders", "Categories" }
        },
        @"C:\ravendb-exports\Northwind.ravendbdump",
        token);

await importOperation.WaitForCompletionAsync();

See ImportAsync and DatabaseSmugglerImportOptions in the Syntax section.

ImportIncrementalAsync​

A RavenDB backup folder contains one full backup file and any number of incremental backup files accumulated since the last full backup.
Use ImportIncrementalAsync to import all logical-backup files from a backup folder into an existing database in a single call, instead of importing each file individually.

After finding all backup files in the specified folder, the method orders them chronologically and imports them in sequence.
Indexes and Subscriptions are excluded from all files except the last, ensuring only their most recent state is applied.

ImportIncrementalAsync imports your backup into an existing database.
To create a new database from backup, use RestoreBackupOperation.

Example​

// Import all backup files from a backup folder into an existing database
await store.Smuggler.ImportIncrementalAsync(
    new DatabaseSmugglerImportOptions(),
    @"C:\RavenDB\Backups\Northwind.2024-01-15T12-00-00");

See ImportIncrementalAsync and DatabaseSmugglerImportOptions in the Syntax section.

TransformScript​

TransformScript lets you modify or filter out each document during an export or import, using JavaScript that you provide.

The JavaScript engine is the same one used for patching operations, so you have identical syntax and capabilities, plus the ability to filter out a document by throwing a skip exception.

var id = this['@metadata']['@id'];
if (id === 'orders/999-A')
    throw 'skip'; // filter-out

this.Freight = 15.3;

Syntax​

Methods​

Smuggler methods​

Switches Smuggler to operate on a database other than the document store's default database.

public DatabaseSmuggler ForDatabase(string databaseName);

Usage:

var northwindSmuggler = store.Smuggler.ForDatabase("Northwind");

ParameterTypeDescription
databaseNamestringThe database that Smuggler will operate on.
Return value
DatabaseSmugglerA Smuggler instance scoped to the specified database.

Classes​

Smuggler options classes​

Options that control what an export includes.

class DatabaseSmugglerExportOptions
{
    DatabaseItemType OperateOnTypes
    DatabaseRecordItemType OperateOnDatabaseRecordTypes
    bool IncludeExpired
    bool IncludeArtificial
    bool IncludeArchived
    bool RemoveAnalyzers
    string TransformScript
    int MaxStepsForTransformScript
    string EncryptionKey
    List<string> Collections
    int? MaxReadOpsPerSecond
    bool SkipCorruptedData
    ExportCompressionAlgorithm? CompressionAlgorithm
}

PropertyTypeDescription
CollectionsList<string>List of specific collections to export. If empty, all collections are exported.
Default: empty
OperateOnTypesDatabaseItemTypeIndicates what should be exported.
Default: Indexes, Documents, RevisionDocuments, Conflicts, DatabaseRecord, ReplicationHubCertificates, Identities, CompareExchange, Attachments, CounterGroups, Subscriptions, TimeSeries, TimeSeriesDeletedRanges
OperateOnDatabaseRecordTypesDatabaseRecordItemTypeIndicates what should be exported from the database record.
Default: Client, ConflictSolverConfig, Expiration, ExternalReplications, PeriodicBackups, RavenConnectionStrings, RavenEtls, Revisions, Settings, SqlConnectionStrings, Sorters, SqlEtls, HubPullReplications, SinkPullReplications, TimeSeries, DocumentsCompression, Analyzers, LockMode, OlapConnectionStrings, OlapEtls, ElasticSearchConnectionStrings, ElasticSearchEtls, PostgreSQLIntegration, QueueConnectionStrings, QueueEtls, IndexesHistory, Refresh, DataArchival, QueueSinks, SnowflakeEtls, SnowflakeConnectionStrings, EmbeddingsGenerations, AiConnectionStrings, GenAiEtls, AiAgents, RemoteAttachments, SchemaValidation
IncludeExpiredboolShould expired documents be exported.
Default: true
IncludeArtificialboolShould artificial documents be exported.
Default: false
IncludeArchivedboolShould archived documents be exported.
Default: true
RemoveAnalyzersboolShould analyzers be removed from indexes.
Default: false
TransformScriptstringJavaScript applied to every exported document. See TransformScript.
MaxStepsForTransformScriptintMaximum number of steps the transform script can run before failing.
Default: 10000
EncryptionKeystringEncryption key used to encrypt the exported file.
Default: null
MaxReadOpsPerSecondint?Limits the read-operation rate during the export, to throttle the load placed on the database.
Default: null (no limit)
SkipCorruptedDataboolWhen true, the export continues if corrupted data is encountered (for example, lost compression dictionaries), recording an error entry in the result report instead of stopping.
Default: false
CompressionAlgorithmExportCompressionAlgorithm?Compression algorithm used for the exported file: Zstd or Gzip.
Default: null

In this article