Skip to main content

What is Smuggler

C#JavaNode.js

  • Smuggler is a tool for moving data between databases.
    Use it to export documents, indexes, and other items from a database as JSON,
    and to import that data into another database.

  • Smuggler is exposed through the DocumentStore.Smuggler property.

  • An export can write to a .ravendbdump file or stream directly into another database.
    An import reads that data back into a database.

  • You can narrow what is transferred by collection, by item type,
    and by applying a transform script to each document.

  • In this article:

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.

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
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