# Migrator

Artifact: [androidx.appsearch:appsearch](https://developer.android.com/jetpack/androidx/releases/appsearch) [View Source](https://cs.android.com/search?q=file:androidx/appsearch/app/Migrator.java+class:androidx.appsearch.app.Migrator) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

*** ** * ** ***


```
abstract class Migrator
```

<br />

*** ** * ** ***

A migrator class to translate `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` from different version of `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema`

Make non-backwards-compatible changes will delete all stored documents in old schema. You can save your documents by setting `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator` via the `https://developer.android.com/reference/kotlin/androidx/appsearch/app/SetSchemaRequest.Builder#setMigrator(java.lang.String,androidx.appsearch.app.Migrator)` for each type and target version you want to save.

`https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#onDowngrade(int,int,androidx.appsearch.app.GenericDocument)` or `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#onUpgrade(int,int,androidx.appsearch.app.GenericDocument)` will be triggered if the version number of the schema stored in AppSearch is different with the version in the request.

If any error or Exception occurred in the `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#onDowngrade(int,int,androidx.appsearch.app.GenericDocument)` or `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#onUpgrade(int,int,androidx.appsearch.app.GenericDocument)`, all the setSchema request will be rejected unless the schema changes are backwards-compatible, and stored documents won't have any observable changes.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#Migrator()()` |

| ### Public functions |
|---|---|
| `abstract https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` | `@https://developer.android.com/reference/kotlin/androidx/annotation/WorkerThread https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#onDowngrade(int,int,androidx.appsearch.app.GenericDocument)( currentVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, finalVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, document: https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument )` Migrates `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` to an older version of `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema`. |
| `abstract https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` | `@https://developer.android.com/reference/kotlin/androidx/annotation/WorkerThread https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#onUpgrade(int,int,androidx.appsearch.app.GenericDocument)( currentVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, finalVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, document: https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument )` Migrates `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` to a newer version of `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema`. |
| `abstract https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#shouldMigrate(int,int)(currentVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, finalVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Returns `true` if this migrator's source type needs to be migrated to update from currentVersion to finalVersion. |

## Public constructors

### Migrator

Added in 1.1.0

```
Migrator()
```

## Public functions

### onDowngrade

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
@WorkerThread
abstract fun onDowngrade(
    currentVersion: Int,
    finalVersion: Int,
    document: GenericDocument
): GenericDocument
```

Migrates `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` to an older version of `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema`.

This method will be invoked only if the `https://developer.android.com/reference/kotlin/androidx/appsearch/app/SetSchemaRequest` is setting a lower version number than the current `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema` saved in AppSearch.

If this `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator` is provided to cover a compatible schema change via `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSession#setSchemaAsync(androidx.appsearch.app.SetSchemaRequest)`, documents under the old version won't be removed unless you use the same document ID.

This method will be invoked on the background worker thread.

| Parameters |
|---|---|
| `currentVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The current version of the document's schema. |
| `finalVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The final version that documents need to be migrated to. |
| `document: https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` | The `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` need to be translated to new version. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` | A `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` in new version. |

### onUpgrade

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
@WorkerThread
abstract fun onUpgrade(
    currentVersion: Int,
    finalVersion: Int,
    document: GenericDocument
): GenericDocument
```

Migrates `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` to a newer version of `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema`.

This method will be invoked only if the `https://developer.android.com/reference/kotlin/androidx/appsearch/app/SetSchemaRequest` is setting a higher version number than the current `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSchema` saved in AppSearch.

If this `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator` is provided to cover a compatible schema change via `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSession#setSchemaAsync(androidx.appsearch.app.SetSchemaRequest)`, documents under the old version won't be removed unless you use the same document ID.

This method will be invoked on the background worker thread provided via `https://developer.android.com/reference/kotlin/androidx/appsearch/app/AppSearchSession#setSchemaAsync(androidx.appsearch.app.SetSchemaRequest)`.

| Parameters |
|---|---|
| `currentVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The current version of the document's schema. |
| `finalVersion: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The final version that documents need to be migrated to. |
| `document: https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` | The `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` need to be translated to new version. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` | A `https://developer.android.com/reference/kotlin/androidx/appsearch/app/GenericDocument` in new version. |

### shouldMigrate

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/appsearch#1.1.0)

```
abstract fun shouldMigrate(currentVersion: Int, finalVersion: Int): Boolean
```

Returns `true` if this migrator's source type needs to be migrated to update from currentVersion to finalVersion.

Migration won't be triggered if currentVersion is equal to finalVersion even if `https://developer.android.com/reference/kotlin/androidx/appsearch/app/Migrator#shouldMigrate(int,int)` return true;