You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
1752: v0.28 dumps r=maryamsulemani97 a=dichotommy
Changes related to the dump API in v0.28. For a full description of these changes, see the [associated issue](#1703).
To do:
- [ ] Fix links (only if necessary for merge, as the links are not actually broken, just dependent on changes made in another PR)
Co-authored-by: Tommy Melvin <[email protected]>
Co-authored-by: Tommy <[email protected]>
Co-authored-by: Maryam <[email protected]>
Co-authored-by: Maryam Sulemani <[email protected]>
|`uid`| integer | The unique sequential identifier of the task |
33
-
|`indexUid`| string | The unique index identifier |
34
-
|`status`| string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`|
35
-
|`type`| string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentDeletion`, `settingsUpdate`|
36
-
|`details`| object | Detailed information on the task payload |
37
-
|`error`| object | Error details and context. Only present when a task has the `failed` status |
38
-
|`duration`| string | The total elapsed time the task spent in the `processing` state, in ISO 8601 format |
39
-
|`enqueuedAt`| string | The date and time when the task was first `enqueued`, in RFC 3339 format |
40
-
|`startedAt`| string | The date and time when the task began `processing`, in RFC 3339 format |
41
-
|`finishedAt`| string | The date and time when the task finished processing, whether `failed` or `succeeded`, in RFC 3339 format. |
|`uid`| integer | The unique sequential identifier of the task |
33
+
|`indexUid`| string | The unique index identifier (always `null` for dumps) |
34
+
|`status`| string | The status of the task. Possible values are `enqueued`, `processing`, `succeeded`, `failed`|
35
+
|`type`| string | The type of task. Possible values are `indexCreation`, `indexUpdate`, `indexDeletion`, `documentAdditionOrUpdate`, `documentPartial`, `documentDeletion`, `settingsUpdate`, `clearAll`, `dumpCreation`|
36
+
|`details`| object | Detailed information on the task payload |
37
+
|`error`| object | Error details and context. Only present when a task has the `failed` status |
38
+
|`duration`| string | The total elapsed time the task spent in the `processing` state, in ISO 8601 format |
39
+
|`enqueuedAt`| string | The date and time when the task was first `enqueued`, in RFC 3339 format |
40
+
|`startedAt`| string | The date and time when the task began `processing`, in RFC 3339 format |
41
+
|`finishedAt`| string | The date and time when the task finished processing, whether `failed` or `succeeded`, in RFC 3339 format. |
42
42
43
43
If a task fails due to an error, all error fields will be appended to the task response in an `error` object.
44
44
45
45
### Summarized task objects
46
46
47
47
All asynchronous operations return a summarized version of [the full `task` object](#task-api-response). It contains the following fields in the stated order:
|`indexUid`| string | Unique index identifier (always `null` for dumps)|
53
+
|`status`| string | Status of the task. Value is `enqueued`|
54
+
|`type`| string | Type of task |
55
+
|`enqueuedAt`| string | Represents the date and time in the RFC 3339 format when the task has been `enqueued`|
56
56
57
57
You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task).
58
58
@@ -139,11 +139,7 @@ Had the task failed, the response would have included an `error` object:
139
139
3. Once the task has completed processing, Meilisearch marks it as `succeeded`, if it was successful, or `failed`, if there was an error.
140
140
4. Tasks marked as `succeeded` or `failed` are not deleted and will remain visible in [the task list](/reference/api/tasks.md#get-tasks)
141
141
142
-
### Dumps
143
-
144
-
While dumps and tasks are both asynchronous operations, they use separate queues and behave differently. For instance, creating a new dump will freeze the task queue until the dump has been generated.
145
-
146
-
[You can read more about dumps in our dedicated guide.](/learn/advanced/dumps.md)
142
+
Tasks are processed in the order they were enqueued, with one exception: `dumpCreation`. Dumps are prioritized over all other tasks in the queue. Their task `uid` still reflects when they were enqueued relative to other tasks.
147
143
148
144
## Terminate Meilisearch while a task is being processed
A dump is a compressed file containing an export of your Meilisearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset. A dump can be imported when launching Meilisearch, but be advised that it may take some time to index all the documents within.
3
+
A dump is a compressed file containing an export of your Meilisearch instance. It contains all your indexes, documents, and settings, but in a raw unprocessed form. A dump isn't an exact copy of your database—it is closer to a blueprint that allows you to create an identical dataset.
4
+
5
+
A dump can be imported when launching Meilisearch, but be advised that it may take some time to index.
4
6
5
7
## Creating a dump
6
8
7
9
To create a dump of your dataset, you need to use the appropriate HTTP route: [`POST /dumps`](/reference/api/dump.md#create-a-dump). The dump creation process is an asynchronous task that takes time proportional to the size of your dataset.
8
10
9
11
<CodeSamplesid="post_dump_1" />
10
12
11
-
The above code triggers a dump creation process. It also returns an object containing information about the dump:
13
+
The above code triggers a dump creation process. It also returns a [summarized task object](/learn/advanced/asynchronous_operations.md#summarized-task-objects) that you can use to check the status of your dump.
12
14
13
-
```
15
+
```json
14
16
{
15
-
"uid": "20200929-114144097",
16
-
"status": "in_progress",
17
-
"startedAt": "2020-09-29T11:41:44.392327Z"
17
+
"taskUid": 1,
18
+
"indexUid": null,
19
+
"status": "enqueued",
20
+
"type": "dumpCreation",
21
+
"enqueuedAt": "2022-06-21T16:10:29.217688Z"
18
22
}
19
23
```
20
24
21
-
You can use the returned `uid` (unique identifier indicating when the dump was triggered) to track its progress with the [get dump status route](/reference/api/dump.md#get-dump-status). The returned status could be:
22
-
23
-
-`in_progress`: Dump creation is in progress
24
-
-`failed`: An error occurred during dump process, and the task was aborted
25
-
-`done`: Dump creation is finished and was successful
25
+
In the below command, replace `1` with the `taskUid` returned by the previous command.
26
26
27
-
<CodeSamplesid="get_dump_status_1" />
27
+
<CodeSamplesid="get_task_1" />
28
28
29
-
The above code sample returns an object with the following details about the dump:
29
+
This command should return an object with detailed information about the dump operation:
30
30
31
-
```
31
+
```json
32
32
{
33
-
"uid": "20200929-114144097",
34
-
"status": "done",
35
-
"startedAt": "2020-09-29T11:41:44.392327Z",
36
-
"finishedAt": "2020-09-29T11:41:50.792147Z"
33
+
"uid": 1,
34
+
"indexUid": null,
35
+
"status": "succeeded",
36
+
"type": "dumpCreation",
37
+
"details": {
38
+
"dumpUid": "20220621-161029217"
39
+
},
40
+
"duration": "PT0.025872S",
41
+
"enqueuedAt": "2022-06-21T16:10:29.217688Z",
42
+
"startedAt": "2022-06-21T16:10:29.218297Z",
43
+
"finishedAt": "2022-06-21T16:10:29.244169Z"
37
44
}
38
45
```
39
46
40
-
After dump creation is finished, the dump file is added to the dump directory. By default, this folder is named `dumps` and can be found in the same directory as your Meilisearch binary. You can customize [this using the `--dumps-dir` configuration option](/learn/configuration/instance_options.md#dumps-destination). **If the dump directory does not already exist when the dump creation process is called, Meilisearch will create it.**
47
+
After dump creation is finished—when `status` is `succeeded`—the dump file is added to the dump directory. By default, this folder is named `dumps` and can be found in the same directory as your Meilisearch binary. You can customize [this using the `--dumps-dir` configuration option](/learn/configuration/instance_options.md#dumps-destination). **If the dump directory does not already exist when the dump creation process is called, Meilisearch will create it.**
41
48
42
49
If a dump file is visible in the file system, the dump process was successfully completed. **Meilisearch will never create a partial dump file**, even if you interrupt an instance while it is generating a dump.
43
50
44
-
::: note
45
-
Unlike [tasks](/learn/advanced/asynchronous_operations.md), dumps have no queue. **Meilisearch only processes one dump at a time.** If you attempt to create a dump while another dump is still processing, Meilisearch will throw an [error](/reference/api/error_codes.md#dump-already-processing).
46
-
47
-
Meilisearch does not process tasks during dump creation, but you can still add new requests to the task queue. This is also true for [snapshots](/learn/advanced/snapshots.md#snapshots).
48
-
:::
49
-
50
-
::: warning
51
-
If you restart Meilisearch after creating a dump, you will not be able to use the dumps endpoint to find out that dump's `status`. This has no effect on the dump file itself.
52
-
:::
53
-
54
51
## Importing a dump
55
52
56
53
When a dump is being imported, the API is not available to the task queue. As a result, no read or write operations can be performed until the importing process is complete.
57
54
58
-
Dumps in v0.20.0 and below are no longer compatible with the new versions. Before you start importing, check your [Meilisearch version](/reference/api/version.md#example) and proceed accordingly.
55
+
Dumps from v0.20.0 and below are no longer compatible with the new versions. Before you start importing, check your [Meilisearch version](/reference/api/version.md#example) and proceed accordingly.
59
56
60
57
::: note
61
-
We do not recommend using dumps from a new Meilisearch version to import an older version.
58
+
We do not recommend using dumps to migrate from a new Meilisearch version to an older one.
62
59
63
60
For example, you can import a dump from Meilisearch v0.21 into v0.22 without any problems. Importing a dump generated in v0.22 into a v0.21 instance, however, can lead to unexpected behavior.
64
61
:::
@@ -79,4 +76,4 @@ If you are using Meilisearch v0.20 or below, migration should be done in two ste
79
76
80
77
## Use cases
81
78
82
-
Dumps are used to restore your database after [updating Meilisearch](/learn/advanced/updating.md) or to copy your database to other Meilisearch instances without having to worry about their respective versions.
79
+
Dumps are used to restore your database after [updating Meilisearch](/learn/advanced/updating.md) or to copy your database to other Meilisearch instances without having to worry about their respective versions. For more on this subject, see a [comparison of snapshots and dumps](/learn/advanced/snapshots_vs_dumps.md).
Copy file name to clipboardExpand all lines: learn/advanced/updating.md
+18-11Lines changed: 18 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -206,24 +206,31 @@ The server should return a response that looks like this:
206
206
207
207
```json
208
208
{
209
-
"uid": "20210212-151153878",
210
-
"status": "in_progress",
211
-
"startedAt": "2021-02-12T15:11:53.402327Z"
209
+
"taskUid": 1,
210
+
"indexUid": null,
211
+
"status": "enqueued",
212
+
"type": "dumpCreation",
213
+
"enqueuedAt": "2022-06-21T16:10:29.217688Z"
212
214
}
213
215
```
214
216
215
-
This process can take some time. Since dump creation is an [asynchronous operation](/learn/advanced/asynchronous_operations.md), you can use the returned `uid`to [track its status](/reference/api/dump.md#get-dump-status).
217
+
This command returns a `taskUid`. You can use this to [track the status](/reference/api/tasks.md#get-one-task) of your dump. Keep in mind that the process can take some time to complete.
Copy file name to clipboardExpand all lines: reference/api/dump.md
+12-33Lines changed: 12 additions & 33 deletions
Original file line number
Diff line number
Diff line change
@@ -6,19 +6,21 @@ Creating a dump is also referred to as exporting it, whereas launching Meilisear
6
6
7
7
During a [dump export](/reference/api/dump.md#create-a-dump), all indexes of the current instance are exported—together with their documents and settings—and saved as a single `.dump` file.
8
8
9
-
During a dump import, all indexes contained in the indicated `.dump` file are imported along with their associated documents and settings. Any existing index with the same uid as an index in the dump file will be overwritten.
9
+
During a dump import, all indexes contained in the indicated `.dump` file are imported along with their associated documents and settings. Any existing index with the same `uid` as an index in the dump file will be overwritten.
10
10
11
11
Dump imports must be performed when launching a Meilisearch instance [using the `import-dump` command-line option](/learn/configuration/instance_options.md#import-dump).
12
12
13
+
[Learn more about dumps](/learn/advanced/dumps.md).
14
+
13
15
## Create a dump
14
16
15
17
<RouteHighlightermethod="POST"route="/dumps"/>
16
18
17
-
Triggers a dump creation process. Once the process is complete, a dump is created in the [dumps directory](/learn/configuration/instance_options.md#dumps-destination). If the dumps directory does not exist yet, it will be created.
19
+
Triggers a dump creation task. Once the process is complete, a dump is created in the [dumps directory](/learn/configuration/instance_options.md#dumps-destination). If the dumps directory does not exist yet, it will be created.
18
20
19
-
**Meilisearch only processes one dump at a time.** If you attempt to create a dump while another dump is still processing, Meilisearch will throw a [`dump_already_processing` error](/reference/api/error_codes.md#dump-already-processing).
21
+
Dump tasks take priority over all other tasks in the queue. This means that a newly created dump task will be processed as soon as the current task is finished.
20
22
21
-
The task queue will not process any further tasks during dump creation, but you can still add new requests to the queue.
23
+
[Learn more about asynchronous operations](/learn/advanced/asynchronous_operations.md).
22
24
23
25
### Example
24
26
@@ -28,35 +30,12 @@ The task queue will not process any further tasks during dump creation, but you
Get the status of a dump creation process using the uid returned after calling the [dump creation route](/reference/api/dump.md#create-a-dump). The dump `uid` is required.
42
-
43
-
The returned status could be:
44
-
45
-
-`in_progress`: Dump creation is in progress
46
-
-`failed`: An error occurred during dump process, and the task was aborted
47
-
-`done`: Dump creation is finished and was successful
48
-
49
-
### Example
50
-
51
-
<CodeSamplesid="get_dump_status_1" />
52
-
53
-
#### Response: `200 Ok`
54
-
55
-
```json
56
-
{
57
-
"uid": "20200929-114144097",
58
-
"status": "done",
59
-
"startedAt": "2020-09-29T11:41:44.392327Z",
60
-
"finishedAt": "2020-09-29T11:41:50.792147Z"
61
-
}
62
-
```
41
+
You can use this `taskUid` to get more details on [the status of the task](/reference/api/tasks.md#get-one-task)
![bors[bot]](https://avatars.githubusercontent.com/in/1847?v=4&size=40){kind=avatar}
0 commit comments