Question regarding the name field in references object when Importing Kibana Objects

Dear All,

I have been working in a script that replicates all the Kibana objects (index-patterns, searches, visualizations and dashboards) from a source server into others. I am using the Bulk Create Saved Objects API, with good results. Nevertheless, It came to my awareness that, that in regards references, I should be using the the name field (of the object a suppose) to define reference to an object, as per the documentation:

" references

(Optional, array) Objects with name , id , and type properties that describe the other saved objects in the referenced object. To refer to the other saved object, use name in the attributes. Never use id to refer to the other saved object. id can be automatically updated during migrations, import, or export."[1]

But there is no "name" attribute within the attributes of the object, I have been trying to find this "name field" with diverse APIs, but I do not find any reference to it, ie. the find api [2]. The import works flawless using the objects Ids, but in this case I am setting the ids during import, so I do not let Kibana create random ids and avoid the warning stated previously in [1]

So my question is, to what does the documentation refers as "name" in this context? is it the title?
or something else?

We are using Kibana 7.0.1 in all of our installations.

[1] (Browsed Feb 11th, 2020)

[2] (Browsed on Feb 11th, 2020), it actually contradicts the [1], as this only export as references the object type and the object id of the reference

Thanks in advance,


Hi @ecarmona,

thanks for your question, this is definitely something that can be improved in the documentation.

In this context name is not referring to a specific field in the saved object, it's referring to the value of the name property of the reference itself. The reason for this is that the ids of the references can change through automated processes (e.g. migrations or imports/exports) while the names won't.

Let's take the following example (a dashboard embedding a single visualization):

  "_index" : ".kibana_1",
  "_id" : "dashboard:af3e13b0-4d8d-11ea-aab7-9d73bac131b0",
  "_version" : 1,
  "_seq_no" : 276,
  "_primary_term" : 1,
  "found" : true,
  "_source" : {
    "dashboard" : {
      "title" : "gjhgjh",
      "hits" : 0,
      "description" : "",
      "panelsJSON" : """[{"version":"8.0.0","gridData":{"w":24,"h":15,"x":0,"y":0,"i":"655c3dd9-00cc-4dd2-a38a-c9fe43fc2b50"},"panelIndex":"655c3dd9-00cc-4dd2-a38a-c9fe43fc2b50","embeddableConfig":{},"panelRefName":"panel_0"}]""",
      "optionsJSON" : """{"useMargins":true,"hidePanelTitles":false}""",
      "version" : 1,
      "timeRestore" : false,
      "kibanaSavedObjectMeta" : {
        "searchSourceJSON" : """{"query":{"query":"","language":"kuery"},"filter":[]}"""
    "type" : "dashboard",
    "references" : [
        "name" : "panel_0",
        "type" : "visualization",
        "id" : "09ffee60-b88c-11e8-a6d9-e546fe2bba5f"
    "migrationVersion" : {
      "dashboard" : "7.3.0"
    "updated_at" : "2020-02-12T11:49:11.403Z"

The dashboard is referencing a visualization, but the id of the visualization (09ffee60-b88c-11e8-a6d9-e546fe2bba5f) is not mentioned within the panelsJSON property. Instead the reference defines a name for this visualization (panel_0) which is used within panelsJSON: ...elIndex":"655c3dd9-00cc-4dd2-a38a-c9fe43fc2b50","embeddableConfig":{},"panelRefName":"panel_0"}]

If a migration script would migrate this visualization and change its id in the process, Kibana just has to update the references list and replace the id there with the new one while leaving the name unchanged. If the name "panel_0" wouldn't be there and the dashboard saved object would use the id directly within the panelsJSON like this: ...elIndex":"655c3dd9-00cc-4dd2-a38a-c9fe43fc2b50","embeddableConfig":{},"panelRefName":"09ffee60-b88c-11e8-a6d9-e546fe2bba5f"}], Kibana would have to look through all properties of the saved object to check whether the visualization id (which got changed) is used somewhere (basically by doing a string search/replace) - a setup like this is just looking for bugs because there are tons of edge cases where this would not work correctly and would produce problems hard to track down to the specific cause.

To summarize - Within the custom properties of your saved object you should never persist the id of other saved objects - always use the indirection of the reference name instead, because saved object ids are not guaranteed to be stable.

1 Like

Thanks @flash1293,

Now, it is more clear for me now. I just have omit the id field. Firstly for the object itself and in the references, Kibana will create the ids internally.

Thanks again.



This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.