|
| 1 | +[[saved-object-ids]] |
| 2 | +=== Saved Object IDs |
| 3 | + |
| 4 | +In the past, many saved object types could have the same ID in different <<xpack-spaces,spaces>>. For example, if you copied dashboard "123" |
| 5 | +from the one space to another space, the second dashboard would also have an ID of "123". While the saved object ID is not something |
| 6 | +that users would interact with directly, many aspects of {kib} rely on it, notably URLs. If you have a "deep link" URL to a saved dashboard, |
| 7 | +that URL includes the saved object ID. |
| 8 | + |
| 9 | +**Starting in the 8.0 release**, {kib} requires most saved objects to have _globally unique_ IDs. This is a change that we needed to make to |
| 10 | +support sharing saved objects to multiple spaces. Most saved objects cannot be shared to multiple spaces _yet_, but we needed to start |
| 11 | +enforcing globally unique object IDs first. |
| 12 | + |
| 13 | +We have made several enhancements to minimize the impact, and this document describes what you need to know about the changes and |
| 14 | +how it will affect you. |
| 15 | + |
| 16 | +[[saved-object-ids-impact-upon-upgrading]] |
| 17 | +==== Impact upon upgrading to 8.x |
| 18 | + |
| 19 | +Every time you upgrade {kib}, <<saved-object-migrations,saved objects are migrated to a new format>>. When you |
| 20 | +first upgrade from 7.x to 8.x, this migration process will start enforcing globally unique saved object IDs. |
| 21 | + |
| 22 | +In practical terms, **any old saved objects that exist in a custom space will have their IDs changed to a new UUID**, while saved objects in |
| 23 | +the Default space will be unchanged. This is how we can ensure that every saved object ID is unique. For example: if you had dashboard "123" |
| 24 | +in the Default space and dashboard "123" in Another space, after the upgrade you would have dashboard "123" in the Default space and |
| 25 | +dashboard "456" in Another space. |
| 26 | + |
| 27 | +[[saved-object-ids-impact-when-using]] |
| 28 | +==== Impact when using 8.x |
| 29 | + |
| 30 | +After you upgrade, or if you set up a new {kib} instance using 8.x, there are a few more things that behave differently. |
| 31 | + |
| 32 | +[[saved-object-ids-impact-when-using-legacy-urls]] |
| 33 | +===== Accessing saved objects using old URLs |
| 34 | + |
| 35 | +When you upgrade {kib} and saved object IDs change, the "deep link" URLs to access those saved objects will also change. To reduce the impact, |
| 36 | +each existing URL is preserved with a special <<legacy-url-aliases,legacy URL alias>>. This means that if you use a bookmark for |
| 37 | +a saved object ID that was changed, you'll be redirected to the new URL for that saved object. |
| 38 | + |
| 39 | +[[saved-object-ids-impact-when-using-import-and-copy]] |
| 40 | +===== Importing and copying saved objects |
| 41 | + |
| 42 | +When you <<managing-saved-objects-copy-to-space,copy a saved object to another space>>, {kib} effectively |
| 43 | +<<managing-saved-objects-export-objects,exports it and imports it into that space>>. In this way, copying a saved object has always behaved |
| 44 | +like an import. In this document when we say "import", it applies to both features. |
| 45 | + |
| 46 | +Historically, whether you imported or copied a saved object, {kib} would create _at most_ one copy of a saved object in that space. If you |
| 47 | +imported the saved object multiple times, {kib} would overwrite the existing object, because it used the same ID. Since saved object IDs are |
| 48 | +now globally unique, {kib} maintains this functionality by tracking each saved object's _origin_. When you import an object in 8.x, {kib} |
| 49 | +uses either the saved object ID _or_ the origin to determine its destination. |
| 50 | + |
| 51 | +If you import a saved object using the "Check for existing objects" option -- whether it was exported from 7.x or 8.x -- {kib} will |
| 52 | +take the following steps: |
| 53 | + |
| 54 | +1. If {kib} finds a matching saved object with the exact same ID in the target space, that will be the import destination -- you can **overwrite** that |
| 55 | +destination or **skip** it. |
| 56 | + |
| 57 | +2. Otherwise, if {kib} finds a matching saved object with a _different_ ID that has the same origin, that will be the import destination |
| 58 | +-- again, you can **overwrite** that destination or **skip** it. |
| 59 | + |
| 60 | +3. Otherwise, if a saved object with the exact same ID exists in a _different_ space, then {kib} will generate a random ID for the import |
| 61 | +destination, preserving the saved object's origin. |
| 62 | + |
| 63 | +4. Otherwise, {kib} creates the saved object with the given ID. |
| 64 | + |
| 65 | +For example, you have a saved object in an `export.ndjson` file, and you set up a brand new {kib} instance. You attempt to import the saved |
| 66 | +object using the "Check for existing objects" and "Automatically overwrite conflicts" options. The first time you import the saved object, |
| 67 | +{kib} will create a new object with the same ID (step 4 above). If you import it again, {kib} will find that object and overwrite it (step 1 |
| 68 | +above). If you then create a _different_ space and import it there, {kib} will create a new object with a random ID (step 3 above). Finally, |
| 69 | +if you import it into the second space again, {kib} will find the second object with a matching origin and overwrite it (step 2 above). |
| 70 | + |
| 71 | +WARNING: When you import a saved object and it is created with a different ID, if 1. it contains weak links to other saved objects (such as |
| 72 | +a dashboard with a Markdown URL to navigate to another dashboard) and 2. the object's ID has changed (step 3 above), those weak links will |
| 73 | +be broken. For more information, refer to <<known-issue-123550,the known issue in the changelog>>. |
| 74 | + |
| 75 | +[[saved-object-ids-impact-when-using-apis]] |
| 76 | +===== Using the saved objects APIs |
| 77 | + |
| 78 | +If you are using the saved objects APIs directly, you should be aware of these changes: |
| 79 | + |
| 80 | +* When using the <<saved-objects-api-create,create>> or <<saved-objects-api-bulk-create,bulk create>> API, you may encounter |
| 81 | + <<saved-objects-api-bulk-create-conflict-errors,conflict errors>> that **cannot** be overridden using the `overwrite: true` |
| 82 | + option. This can occur if there is already a saved object with this ID in a _different_ space, or if there is a legacy URL alias for this |
| 83 | + ID in the same space. |
| 84 | +* When using the <<saved-objects-api-import,import>> or <<spaces-api-copy-saved-objects,copy to space>> API, objects can potentially be |
| 85 | + created with a different ID as described above. |
| 86 | +* When using the <<saved-objects-api-delete,delete>> API, if the saved object exists in multiple spaces, it can only be deleted by using the |
| 87 | + <<saved-objects-api-delete-query-params,`force` option>>. |
0 commit comments