Saved object type definitions should be defined in their own my_plugin/server/saved_objects directory.

The folder should contain a file per type, named after the snake_case name of the type, and an index.ts file exporting all the types.

src/plugins/my_plugin/server/saved_objects/dashboard_visualization.ts.

import { SavedObjectsType } from 'src/core/server';

export const dashboardVisualization: SavedObjectsType = {
  name: 'dashboard_visualization', 
  hidden: true,
  namespaceType: 'multiple-isolated', 
  mappings: {
    dynamic: false,
    properties: {
      description: {
        type: 'text',
      },
      hits: {
        type: 'integer',
      },
    },
  },
  migrations: {
    '1.0.0': migratedashboardVisualizationToV1,
    '2.0.0': migratedashboardVisualizationToV2,
  },
};

src/plugins/my_plugin/server/saved_objects/index.ts.

export { dashboardVisualization } from './dashboard_visualization';
export { dashboard } from './dashboard';

src/plugins/my_plugin/server/plugin.ts.

import { dashboard, dashboardVisualization } from './saved_objects';

export class MyPlugin implements Plugin {
  setup({ savedObjects }) {
    savedObjects.registerType(dashboard);
    savedObjects.registerType(dashboardVisualization);
  }
}

Each Saved Object type can define it’s own Elasticsearch field mappings. Because multiple Saved Object types can share the same index, mappings defined by a type will be nested under a top-level field that matches the type name.

For example, the mappings defined by the dashboard_visualization Saved Object type:

src/plugins/my_plugin/server/saved_objects/dashboard_visualization.ts.

import { SavedObjectsType } from 'src/core/server';

export const dashboardVisualization: SavedObjectsType = {
  name: 'dashboard_visualization',
  ...
  mappings: {
    properties: {
      dynamic: false,
      description: {
        type: 'text',
      },
      hits: {
        type: 'integer',
      },
    },
  },
  migrations: { ... },
};

Will result in the following mappings being applied to the .kibana index:

{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      ...
      "dashboard_vizualization": {
        "dynamic": false,
        "properties": {
          "description": {
            "type": "text",
          },
          "hits": {
            "type": "integer",
          },
        },
      }
    }
  }
}

Do not use field mappings like you would use data types for the columns of a SQL database. Instead, field mappings are analogous to a SQL index. Only specify field mappings for the fields you wish to search on or query. By specifying dynamic: false in any level of your mappings, Elasticsearch will accept and store any other fields even if they are not specified in your mappings.

Since Elasticsearch has a default limit of 1000 fields per index, plugins should carefully consider the fields they add to the mappings. Similarly, Saved Object types should never use dynamic: true as this can cause an arbitrary amount of fields to be added to the .kibana index.

Saved Objects support schema changes between Kibana versions, which we call migrations. Migrations are applied when a Kibana installation is upgraded from one version to the next, when exports are imported via the Saved Objects Management UI, or when a new object is created via the HTTP API.

Each Saved Object type may define migrations for its schema. Migrations are specified by the Kibana version number, receive an input document, and must return the fully migrated document to be persisted to Elasticsearch.

Let’s say we want to define two migrations: - In version 1.1.0, we want to drop the subtitle field and append it to the title - In version 1.4.0, we want to add a new id field to every panel with a newly generated UUID.

First, the current mappings should always reflect the latest or "target" schema. Next, we should define a migration function for each step in the schema evolution:

src/plugins/my_plugin/server/saved_objects/dashboard_visualization.ts

import { SavedObjectsType, SavedObjectMigrationFn } from 'src/core/server';
import uuid from 'uuid';

interface DashboardVisualizationPre110 {
  title: string;
  subtitle: string;
  panels: Array<{}>;
}
interface DashboardVisualization110 {
  title: string;
  panels: Array<{}>;
}

interface DashboardVisualization140 {
  title: string;
  panels: Array<{ id: string }>;
}

const migrateDashboardVisualization110: SavedObjectMigrationFn<
  DashboardVisualizationPre110, 
  DashboardVisualization110
> = (doc) => {
  const { subtitle, ...attributesWithoutSubtitle } = doc.attributes;
  return {
    ...doc, 
    attributes: {
      ...attributesWithoutSubtitle,
      title: `${doc.attributes.title} - ${doc.attributes.subtitle}`,
    },
  };
};

const migrateDashboardVisualization140: SavedObjectMigrationFn<
  DashboardVisualization110,
  DashboardVisualization140
> = (doc) => {
  const outPanels = doc.attributes.panels?.map((panel) => {
    return { ...panel, id: uuid.v4() };
  });
  return {
    ...doc,
    attributes: {
      ...doc.attributes,
      panels: outPanels,
    },
  };
};

export const dashboardVisualization: SavedObjectsType = {
  name: 'dashboard_visualization', 
  /** ... */
  migrations: {
    // Takes a pre 1.1.0 doc, and converts it to 1.1.0
    '1.1.0': migrateDashboardVisualization110,

    // Takes a 1.1.0 doc, and converts it to 1.4.0
    '1.4.0': migrateDashboardVisualization140,  
  },
};

Migrations should be written defensively, an exception in a migration function will prevent a Kibana upgrade from succeeding and will cause downtime for our users. Having said that, if a document is encountered that is not in the expected shape, migrations are encouraged to throw an exception to abort the upgrade. In most scenarios, it is better to fail an upgrade than to silently ignore a corrupt document which can cause unexpected behaviour at some future point in time.

It is critical that you have extensive tests to ensure that migrations behave as expected with all possible input documents. Given how simple it is to test all the branch conditions in a migration function and the high impact of a bug in this code, there’s really no reason not to aim for 100% test code coverage.

It is recommended that plugins only expose Saved Object types that are necessary. That is so to provide better backward compatibility.

There are two options to register a type: either as completely unexposed to the global Saved Objects HTTP APIs and client or to only expose it to the client but not to the APIs.

import { CoreStart, Plugin } from '@kbn/core/server';

class SomePlugin implements Plugin {
  // ...

  public start({ savedObjects }: CoreStart) {
    // ...

    const savedObjectsClient = savedObjects.getScopedClient(
      request,
      { includedHiddenTypes: ['dashboard_visualization'] }
    );

    // ...
  }
}

import { SavedObjectsType } from 'src/core/server';

export const myCustomVisualization: SavedObjectsType = {
  name: 'my_custom_visualization', 
  hidden: false,
  hiddenFromHttpApis: true, 
  namespaceType: 'multiple-isolated',
  mappings: {
    dynamic: false,
    properties: {
      description: {
        type: 'text',
      },
      hits: {
        type: 'integer',
      },
    },
  },
  migrations: {
    '1.0.0': migrateMyCustomVisualizationToV1,
    '2.0.0': migrateMyCustomVisualizationToV2,
  },
};

When a Saved Object declares references to other Saved Objects, the Saved Objects Export API will automatically export the target object with all of its references. This makes it easy for users to export the entire reference graph of an object.

If a Saved Object can’t be used on its own, that is, it needs other objects to exist for a feature to function correctly, that Saved Object should declare references to all the objects it requires. For example, a dashboard object might have panels for several visualization objects. When these visualization objects don’t exist, the dashboard cannot be rendered correctly. The dashboard object should declare references to all its visualizations.

However, visualization objects can continue to be rendered or embedded into other dashboards even if the dashboard it was originally embedded into doesn’t exist. As a result, visualization objects should not declare references to dashboard objects.

For each referenced object, an id, type and name are added to the references array:

router.get(
  { path: '/some-path', validate: false },
  async (context, req, res) => {
    const object = await context.core.savedObjects.client.create(
      'dashboard',
      {
        title: 'my dashboard',
        panels: [
          { visualization: 'vis1' }, 
        ],
        indexPattern: 'indexPattern1'
      },
      { references: [
          { id: '...', type: 'visualization', name: 'vis1' },
          { id: '...', type: 'index_pattern', name: 'indexPattern1' },
        ]
      }
    )
    ...
  }
);