Saved Object IDs
editSaved Object IDs
editIn the past, many saved object types could have the same ID in different spaces. For example, if you copied dashboard "123" 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 that users would interact with directly, many aspects of Kibana rely on it, notably URLs. If you have a "deep link" URL to a saved dashboard, that URL includes the saved object ID.
Starting in the 8.0 release, Kibana requires most saved objects to have globally unique IDs. This is a change that we needed to make to support sharing saved objects to multiple spaces. Most saved objects cannot be shared to multiple spaces yet, but we needed to start enforcing globally unique object IDs first.
We have made several enhancements to minimize the impact, and this document describes what you need to know about the changes and how it will affect you.
Impact upon upgrading to 8.x
editEvery time you upgrade Kibana, saved objects are migrated to a new format. When you first upgrade from 7.x to 8.x, this migration process will start enforcing globally unique saved object IDs.
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 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" in the Default space and dashboard "123" in Another space, after the upgrade you would have dashboard "123" in the Default space and dashboard "456" in Another space.
Impact when using 8.x
editAfter you upgrade, or if you set up a new Kibana instance using 8.x, there are a few more things that behave differently.
Accessing saved objects using old URLs
editWhen you upgrade Kibana and saved object IDs change, the "deep link" URLs to access those saved objects will also change. To reduce the impact, each existing URL is preserved with a special legacy URL alias. This means that if you use a bookmark for a saved object ID that was changed, you’ll be redirected to the new URL for that saved object.
Importing and copying saved objects
editWhen you copy a saved object to another space, Kibana effectively exports it and imports it into that space. In this way, copying a saved object has always behaved like an import. In this document when we say "import", it applies to both features.
Historically, whether you imported or copied a saved object, Kibana would create at most one copy of a saved object in that space. If you imported the saved object multiple times, Kibana would overwrite the existing object, because it used the same ID. Since saved object IDs are now globally unique, Kibana maintains this functionality by tracking each saved object’s origin. When you import an object in 8.x, Kibana uses either the saved object ID or the origin to determine its destination.
If you import a saved object using the "Check for existing objects" option — whether it was exported from 7.x or 8.x — Kibana will take the following steps:
- If Kibana finds a matching saved object with the exact same ID in the target space, that will be the import destination — you can overwrite that destination or skip it.
- Otherwise, if Kibana finds a matching saved object with a different ID that has the same origin, that will be the import destination — again, you can overwrite that destination or skip it.
- Otherwise, if a saved object with the exact same ID exists in a different space, then Kibana will generate a random ID for the import destination, preserving the saved object’s origin.
- Otherwise, Kibana creates the saved object with the given ID.
For example, you have a saved object in an export.ndjson file, and you set up a brand new Kibana instance. You attempt to import the saved
object using the "Check for existing objects" and "Automatically overwrite conflicts" options. The first time you import the saved object,
Kibana will create a new object with the same ID (step 4 above). If you import it again, Kibana will find that object and overwrite it (step 1
above). If you then create a different space and import it there, Kibana will create a new object with a random ID (step 3 above). Finally,
if you import it into the second space again, Kibana will find the second object with a matching origin and overwrite it (step 2 above).
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 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 be broken. For more information, refer to the known issue in the changelog.
Using the saved objects APIs
editIf you are using the saved objects APIs directly, you should be aware of these changes:
-
When using the create or bulk create API, you may encounter
conflict errors that cannot be overridden using the
overwrite: trueoption. 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 ID in the same space. - When using the import or copy to space API, objects can potentially be created with a different ID as described above.
-
When using the delete API, if the saved object exists in multiple spaces, it can only be deleted by using the
forceoption.