* iwp * add docs on saved objects * add saved object docs * Update dev_docs/key_concepts/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/tutorials/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/tutorials/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/tutorials/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/tutorials/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/tutorials/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/tutorials/saved_objects.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * review updates * remove this line, support being added Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com>
251 lines
8.4 KiB
Plaintext
251 lines
8.4 KiB
Plaintext
---
|
||
id: kibDevTutorialSavedObject
|
||
slug: /kibana-dev-docs/tutorial/saved-objects
|
||
title: Register a new saved object type
|
||
summary: Learn how to register a new saved object type.
|
||
date: 2021-02-05
|
||
tags: ['kibana','onboarding', 'dev', 'architecture', 'tutorials']
|
||
---
|
||
|
||
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**
|
||
|
||
```ts
|
||
import { SavedObjectsType } from 'src/core/server';
|
||
|
||
export const dashboardVisualization: SavedObjectsType = {
|
||
name: 'dashboard_visualization', [1]
|
||
hidden: false,
|
||
namespaceType: 'single',
|
||
mappings: {
|
||
dynamic: false,
|
||
properties: {
|
||
description: {
|
||
type: 'text',
|
||
},
|
||
hits: {
|
||
type: 'integer',
|
||
},
|
||
},
|
||
},
|
||
migrations: {
|
||
'1.0.0': migratedashboardVisualizationToV1,
|
||
'2.0.0': migratedashboardVisualizationToV2,
|
||
},
|
||
};
|
||
```
|
||
|
||
[1] Since the name of a Saved Object type forms part of the url path for the public Saved Objects HTTP API,
|
||
these should follow our API URL path convention and always be written as snake case.
|
||
|
||
**src/plugins/my_plugin/server/saved_objects/index.ts**
|
||
|
||
```ts
|
||
export { dashboardVisualization } from './dashboard_visualization';
|
||
export { dashboard } from './dashboard';
|
||
```
|
||
|
||
**src/plugins/my_plugin/server/plugin.ts**
|
||
|
||
```ts
|
||
import { dashboard, dashboardVisualization } from './saved_objects';
|
||
|
||
export class MyPlugin implements Plugin {
|
||
setup({ savedObjects }) {
|
||
savedObjects.registerType(dashboard);
|
||
savedObjects.registerType(dashboardVisualization);
|
||
}
|
||
}
|
||
```
|
||
|
||
## Mappings
|
||
|
||
Each Saved Object type can define its 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**
|
||
|
||
```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:
|
||
|
||
```ts
|
||
{
|
||
"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.
|
||
|
||
## References
|
||
|
||
Declare <DocLink id="kibDevDocsSavedObjectsIntro" section="References" text="Saved Object references"/> by adding an id, type and name to the
|
||
`references` array.
|
||
|
||
```ts
|
||
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' }, [1]
|
||
],
|
||
indexPattern: 'indexPattern1'
|
||
},
|
||
{ references: [
|
||
{ id: '...', type: 'visualization', name: 'vis1' },
|
||
{ id: '...', type: 'index_pattern', name: 'indexPattern1' },
|
||
]
|
||
}
|
||
)
|
||
...
|
||
}
|
||
);
|
||
```
|
||
[1] Note how `dashboard.panels[0].visualization` stores the name property of the reference (not the id directly) to be able to uniquely
|
||
identify this reference. This guarantees that the id the reference points to always remains up to date. If a
|
||
visualization id was directly stored in `dashboard.panels[0].visualization` there is a risk that this id gets updated without
|
||
updating the reference in the references array.
|
||
|
||
## Writing migrations
|
||
|
||
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**
|
||
|
||
```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, [1]
|
||
DashboardVisualization110
|
||
> = (doc) => {
|
||
const { subtitle, ...attributesWithoutSubtitle } = doc.attributes;
|
||
return {
|
||
...doc, [2]
|
||
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', [1]
|
||
/** ... */
|
||
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, [3]
|
||
},
|
||
};
|
||
```
|
||
[1] It is useful to define an interface for each version of the schema. This allows TypeScript to ensure that you are properly handling the input and output
|
||
types correctly as the schema evolves.
|
||
|
||
[2] Returning a shallow copy is necessary to avoid type errors when using different types for the input and output shape.
|
||
|
||
[3] Migrations do not have to be defined for every version. The version number of a migration must always be the earliest Kibana version
|
||
in which this migration was released. So if you are creating a migration which will
|
||
be part of the v7.10.0 release, but will also be backported and released as v7.9.3, the migration version should be: 7.9.3.
|
||
|
||
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.
|