github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-06-27 18:51:07 -04:00
Code Issues Projects Releases Packages Wiki Activity

Update doc slugs to improve analytic tracking, move to appropriate folders (#113630)

Browse source 
* Update the slugs to improve google analytics drilldown tracking

* more slug updates

* Fix some formatting issues in building blocks

* update paths

Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Stacey Gammon 2021-10-04 13:36:45 -04:00 • committed by GitHub
parent a4eab441c0
commit eddbc8db6f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
27 changed files with 219 additions and 218 deletions
Download patch file Download diff file Expand all files Collapse all files

2
dev_docs/key_concepts/anatomy_of_a_plugin.mdx
View file

@ -1,6 +1,6 @@
---
id: kibDevAnatomyOfAPlugin
slug: /kibana-dev-docs/anatomy-of-a-plugin
slug: /kibana-dev-docs/key-concepts/anatomy-of-a-plugin
title: Anatomy of a plugin
summary: Anatomy of a Kibana plugin.
date: 2021-08-03

142
dev_docs/key_concepts/building_blocks.mdx Normal file
View file

@ -0,0 +1,142 @@
---
id: kibBuildingBlocks
slug: /kibana-dev-docs/key-concepts/building-blocks
title: Building blocks
summary: Consider these building blocks when developing your plugin.
date: 2021-02-24
tags: ['kibana', 'onboarding', 'dev', 'architecture']
---
When building a plugin in Kibana, there are a handful of architectural "building blocks" you can use. Some of these building blocks are "higher-level",
and some are "lower-level". High-level building blocks come
with many built-in capabilities, require less maintenance, and evolve new feature sets over time with little to no
impact on consumers. When developers use high-level building blocks, new features are exposed consistently, across all of Kibana, at the same time.
On the downside, they are not as flexible as our low-level building blocks.
Low-level building blocks
provide greater flexibility, but require more code to stitch them together into a meaningful UX. This results in higher maintenance cost for consumers and greater UI/UX variability
across Kibana.
For example, if an application is using <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/> and <DocLink id="kibBuildingBlocks" section="search-source" text="Search Source" />, their application would
automatically support runtime fields. If the app is instead using the lower-level <DocLink
id="kibBuildingBlocks"
section="search-strategy"
text="Search Strategy"
/>, additional work would be required.
Armed with this knowledge, you can choose what works best for your use case!
# Application building blocks
## UI components
The following high-level building blocks can be rendered directly into your application UI.
### Query Bar
The <DocLink id="kibDataPlugin" text="Data plugin"/> provides a high-level Query Bar component that comes with support for Lucene, KQL, Saved Queries,
and <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/>. If you would like to expose the ability to search and filter on Elasticsearch data, the Query Bar provided by the <DocLink id="kibDataPlugin" text="Data plugin" /> is your go-to building block.
**Github labels**: `Team:AppServices`, `Feature:QueryBar`
### Dashboard Embeddable
Add a Dashboard Embeddable directly inside your application to provide users with a set of visualizations and graphs that work seamlessly
with the <DocLink id="kibBuildingBlocks" section="query-bar" text="Query Bar"/>. Every feature that is added to a registered <DocLink id="kibBuildingBlocks" section="embeddables" text="Embeddable" /> (Lens, Maps, Saved Searches and more) will be available automatically, as well as any <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions" /> that are added to the Embeddable context menu panel (for example, drilldowns, custom panel time ranges, and "share to" features).
The Dashboard Embeddable is one of the highest-level UI components you can add to your application.
**Github labels**: `Team:Presentation`, `Feature:Dashboard`
### Lens Embeddable
Check out the Lens Embeddable if you wish to show users visualizations based on Elasticsearch data without worrying about query building and chart rendering. It's built on top of the <DocLink id="kibBuildingBlocks" section="expressions" text="Expression language" />, and integrates with <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns" /> and <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions" />. Using the same configuration, it's also possible to link to a prefilled Lens editor, allowing the user to drill deeper and explore their data.
**Github labels**: `Team:VisEditors`, `Feature:Lens`
### Map Embeddable
Check out the Map Embeddable if you wish to embed a map in your application.
**Github labels**: `Team:Geo`
### KibanaPageTemplate
All Kibana pages should use KibanaPageTemplate to setup their pages. It's a thin wrapper around [EuiPageTemplate](https://elastic.github.io/eui/#/layout/page) that makes setting up common types of Kibana pages quicker and easier while also adhering to any Kibana-specific requirements.
Check out <DocLink id="kibDevDocsKPTTutorial" text="the KibanaPageTemplate tutorial" /> for more implementation guidance.
**Github labels**: `EUI`
## Searching
### Index Patterns
<DocLink id="kibDataPlugin" section="index-patterns-api" text="Index Patterns" /> are a high-level, space-aware
abstraction layer that sits above Data Streams and Elasticsearch indices. Index Patterns provide users
the ability to define and customize the data they wish to search and filter on, on a per-space basis.
For example, users can specify a set of indices, and they can customize the field list with runtime fields,
formatting options and custom labels.
Index Patterns are used in many other high-level building blocks so we highly recommend you consider this building block for your search needs.
**Github labels**: `Team:AppServices`, `Feature:Index Patterns`
### Search Source
<DocLink id="kibDataPlugin" section="searchsource" text="Search Source" /> is a high-level search service
offered by the <DocLink id="kibDataPlugin" section="searchsource" text="Data plugin" />. It requires
an <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Pattern" />, and abstracts away
the raw ES DSL and search endpoint. Internally it uses the ES <DocLink
id="kibBuildingBlocks"
section="search-strategies"
text="Search Strategy"
/>
. Use Search Source if you need to query data from Elasticsearch, and you aren't already using one of
the high-level UI Components that handles this internally.
**Github labels**: `Team:AppServices`, `Feature:Search`
### Search Strategies
Search Strategies are a low-level building block that abstracts away search details, like what REST endpoint is being called. The ES Search Strategy
is a very lightweight abstraction layer that sits just above querying ES with the elasticsearch-js client. Other search stragies are offered for other
languages, like EQL and SQL. These are very low-level building blocks so expect a lot of glue work to make these work with the higher-level abstractions.
**Github labels**: `Team:AppServices`, `Feature:Search`
### Expressions
Expressions are a low-level building block that can be used if you have advanced search needs that requiring piping results into additional functionality, like
joining and manipulating data. Lens and Canvas are built on top of Expressions. Most developers should be able to use <DocLink id="kibBuildingBlocks" section="lens-embeddable" text="Lens" /> or <DocLink id="kibBuildingBlocks" section="search-source" text="Search Source" />, rather than need to
access the Expression language directly.{' '}
**Github labels**: `Team:AppServices`, `Feature:ExpressionLanguage`
## Saved Objects
<DocLink id="kibDevDocsSavedObjectsIntro" text="Saved Objects" /> should be used if you need to persist
application-level information. If you were building a TODO application, each TODO item would be a `Saved
Object`. Saved objects come pre-wired with support for bulk export/import, security features like space
sharing and space isolation, and tags.
**Github labels**: `Team:Core`, `Feature:Saved Objects`
# Integration building blocks
Use the following building blocks to create an inter-connected, cross-application, holistic Kibana experience. These building blocks allow you to expose functionality
that promotes your own application into other applications, as well as help developers of other applications integrate into your app.
## UI Actions & Triggers
Integrate custom actions into other applications by registering UI Actions attached to existing triggers. For example, the Maps
application could register a UI Action called "View in Maps" to appear any time the user clicked a geo field to filter on.
**Github labels**: `Team:AppServices`, `Feature:UIActions`
## Embeddables
Embeddables help you integrate your application with the Dashboard application. Register your custom UI Widget as an Embeddable and users will
be able to add it as a panel on a Dashboard. With a little extra work, it can also be exposed in Canvas workpads.
**Github labels**: `Team:AppServices`, `Feature:Embeddables`

11
dev_docs/key_concepts/data_views.mdx
View file

@ -1,16 +1,16 @@
---
id: kibDataViewsKeyConcepts
slug: /kibana-dev-docs/data-view-intro
slug: /kibana-dev-docs/key-concepts/data-view-intro
title: Data Views
summary: Data views are the central method of defining queryable data sets in Kibana
date: 2021-08-11
tags: ['kibana','dev', 'contributor', 'api docs']
tags: ['kibana', 'dev', 'contributor', 'api docs']
---
*Note: Kibana index patterns are currently being renamed to data views. There will be some naming inconsistencies until the transition is complete.*
_Note: Kibana index patterns are currently being renamed to data views. There will be some naming inconsistencies until the transition is complete._
Data views (formerly Kibana index patterns or KIPs) are the central method of describing sets of indices for queries. Usage is strongly recommended
as a number of high level <DocLink id="kibBuildingBlocks" text="building blocks"/> rely on them. Further, they provide a consistent view of data across
as a number of high level <DocLink id="kibBuildingBlocks" text="building blocks"/> rely on them. Further, they provide a consistent view of data across
a variety Kibana apps.
Data views are defined by a wildcard string (an index pattern) which matches indices, data streams, and index aliases, optionally specify a
@ -20,8 +20,6 @@ on the data view via runtime fields. Schema-on-read functionality is provided by
![image](../assets/data_view_diagram.png)
The data view API is made available via the data plugin (`data.indexPatterns`, soon to be renamed) and most commonly used with <DocLink id="kibDevTutorialDataSearchAndSessions" section="high-level-search" text="SearchSource" />
(`data.search.search.SearchSource`) to perform queries. SearchSource will apply existing filters and queries from the search bar UI.
@ -29,4 +27,3 @@ Users can create data views via [Data view management](https://www.elastic.co/gu
Additionally, they can be created through the data view API.
Data views also allow formatters and custom labels to be defined for fields.

146
dev_docs/key_concepts/kibana_platform_plugin_intro.mdx Normal file
View file

@ -0,0 +1,146 @@
---
id: kibPlatformIntro
slug: /kibana-dev-docs/key-concepts/platform-intro
title: Plugins and the Kibana platform
summary: An introduction to the Kibana platform and how to use it to build a plugin.
date: 2021-01-06
tags: ['kibana', 'onboarding', 'dev', 'architecture']
---
From an end user perspective, Kibana is a tool for interacting with Elasticsearch, providing an easy way
to visualize and analyze data.
From a developer perspective, Kibana is a platform that provides a set of tools to build not only the UI you see in Kibana today, but
a wide variety of applications that can be used to explore, visualize, and act upon data in Elasticsearch. The platform provides developers the ability
to build applications, or inject extra functionality into
already existing applications. Did you know that almost everything you see in the
Kibana UI is built inside a plugin? If you removed all plugins from Kibana, you'd be left with an empty navigation menu, and a set of
developer tools. The Kibana platform is a blank canvas, just waiting for a developer to come along and create something!
![Kibana personas](assets/kibana_platform_plugin_end_user.png)
## Platform services
Plugins have access to three kinds of public services:
- Platform services provided by `core` (<DocLink id="kibPlatformIntro" section="core-services" text="Core services"/>)
- Platform services provided by plugins (<DocLink id="kibPlatformIntro" section="platform-plugins" text="Platform plugins"/>)
- Shared services provided by plugins, that are only relevant for only a few, specific plugins (e.g. "presentation utils").
The first two items are what make up "Platform services".
<DocCallOut title="What is the difference between services provided by platform plugins, and those by core?">
We try to put only the most stable and fundamental code into `Core`, while more application focused functionality goes in a plugin, but the heuristic isn't
clear, and we haven't done a great job of sticking to it. For example, notifications and toasts are core services, but data and search are plugin services.
Today it looks something like this.
![Core vs platform plugins vs plugins](assets/platform_plugins_core.png)
<DocAccordion buttonContent="A bit of history">
When the Kibana platform and plugin infrastructure was built, we thought of two types of code: core services, and other plugin services. We planned to keep the most stable and fundamental
code needed to build plugins inside core.
In reality, we ended up with many platform-like services living outside of core, with no (short term) intention of moving them. We highly encourage plugin developers to use
them, so we consider them part of platform services.
When we built our platform system, we also thought we'd end up with only a handful of large plugins outside core. Users could turn certain plugins off, to minimize the code
footprint and speed up Kibana.
In reality, our plugin model ended up being used like micro-services. Plugins are the only form of encapsulation we provide developers, and they liked it! However, we ended
up with a ton of small plugins, that developers never intended to be uninstallable, nor tested in this manner. We are considering ways to provide developers the ability to build services
with the encapsulation
they desire, without the need to build a plugin.
Another side effect of having many small plugins is that common code often ends up extracted into another plugin. Use case specific utilities are exported,
that are not meant to be used in a general manner. This makes our definition of "platform code" a bit trickier to define. We'd like to say "The platform is made up of
every publically exposed service", but in today's world, that wouldn't be a very accurate picture.
We recognize the need to better clarify the relationship between core functionality, platform-like plugin functionality, and functionality exposed by other plugins.
It's something we will be working on!
</DocAccordion>
We will continue to focus on adding clarity around these types of services and what developers can expect from each.
</DocCallOut>
### Core services
Sometimes referred to just as <DocLink id="kibServerAndCoreComponents" text="Core, Core services"/> provide the most basic and fundamental tools neccessary for building a plugin, like creating saved objects,
routing, application registration, notifications and <DocLink id="kibCoreLogging" text="logging"/>. The Core platform is not a plugin itself, although
there are some plugins that provide platform functionality. We call these <DocLink id="kibPlatformIntro" section="platform-plugins" text="Platform plugins"/>.
### Platform plugins
Plugins that provide fundamental services and functionality to extend and customize Kibana, for example, the
<DocLink id="kibDataPlugin" text="data" /> plugin. There is no official way to tell if a plugin is a
platform plugin or not. Platform plugins are _usually_ plugins that are managed by the Platform Group,
but we are starting to see some exceptions.
## Plugins
Plugins are code that is written to extend and customize Kibana. Plugin's don't have to be part of the Kibana repo, though the Kibana
repo does contain many plugins! Plugins add customizations by
using <DocLink id="kibPlatformIntro" section="extension-points" text="extension points"/> provided by <DocLink id="kibPlatformIntro" section="platform-services" text="platform services"/>.
Sometimes people confuse the term "plugin" and "application". While often there is a 1:1 relationship between a plugin and an application, it is not always the case.
A plugin may register many applications, or none.
### Applications
Applications are top level pages in the Kibana UI. Dashboard, Canvas, Maps, App Search, etc, are all examples of applications:
![applications in kibana](./assets/applications.png)
A plugin can register an application by
adding it to core's application <DocLink id="kibPlatformIntro" section="registry" text="registry"/>.
### Public plugin API
A plugin's public API consists of everything exported from a plugin's <DocLink id="kibPlatformIntro" section="plugin-lifecycle" text="start or setup lifecycle methods"/>,
as well as from the top level `index.ts` files that exist in the three "scope" folders:
- common/index.ts
- public/index.ts
- server/index.ts
Any plugin that exports something from those files, or from the lifecycle methods, is exposing a public service. We sometimes call these things "plugin services" or
"shared services".
## Lifecycle methods
Core, and plugins, expose different features at different parts of their lifecycle. We describe the lifecycle of core services and plugins with
specifically-named functions on the service definition.
Kibana has three lifecycles: setup, start, and stop. Each plugin’s setup function is called sequentially while Kibana is setting up
on the server or when it is being loaded in the browser. The start functions are called sequentially after setup has been completed for all plugins.
The stop functions are called sequentially while Kibana is gracefully shutting down the server or when the browser tab or window is being closed.
The table below explains how each lifecycle relates to the state of Kibana.
| lifecycle | purpose | server | browser |
| --------- | ------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| setup | perform "registration" work to setup environment for runtime | configure REST API endpoint, register saved object types, etc. | configure application routes in SPA, register custom UI elements in extension points, etc. |
| start | bootstrap runtime logic | respond to an incoming request, request Elasticsearch server, etc. | start polling Kibana server, update DOM tree in response to user interactions, etc. |
| stop | cleanup runtime | dispose of active handles before the server shutdown. | store session data in the LocalStorage when the user navigates away from Kibana, etc. |
Different service interfaces can and will be passed to setup, start, and stop because certain functionality makes sense in the context of a running plugin while other types
of functionality may have restrictions or may only make sense in the context of a plugin that is stopping.
## Extension points
An extension point is a function provided by core, or a plugin's plugin API, that can be used by other
plugins to customize the Kibana experience. Examples of extension points are:
- core.application.register (The extension point talked about above)
- core.notifications.toasts.addSuccess
- core.overlays.showModal
- embeddables.registerEmbeddableFactory
- uiActions.registerAction
- core.saedObjects.registerType
## Follow up material
Learn how to build your own plugin by following <DocLink id="kibHelloWorldApp" />.

20
dev_docs/key_concepts/performance.mdx
View file

@ -1,6 +1,6 @@
---
id: kibDevPerformance
slug: /kibana-dev-docs/performance
slug: /kibana-dev-docs/key-concepts/performance
title: Performance
summary: Performance tips for Kibana development.
date: 2021-09-02
@ -9,13 +9,13 @@ tags: ['kibana', 'onboarding', 'dev', 'performance']
## Keep Kibana fast
*tl;dr*: Load as much code lazily as possible. Everyone loves snappy
_tl;dr_: Load as much code lazily as possible. Everyone loves snappy
applications with a responsive UI and hates spinners. Users deserve the
best experience whether they run Kibana locally or
in the cloud, regardless of their hardware and environment.
There are 2 main aspects of the perceived speed of an application: loading time
and responsiveness to user actions. Kibana loads and bootstraps *all*
and responsiveness to user actions. Kibana loads and bootstraps _all_
the plugins whenever a user lands on any page. It means that
every new application affects the overall _loading performance_, as plugin code is
loaded _eagerly_ to initialize the plugin and provide plugin API to dependent
@ -60,12 +60,12 @@ export class MyPlugin implements Plugin<MyPluginSetup> {
### Understanding plugin bundle size
Kibana Platform plugins are pre-built with `@kbn/optimizer`
Kibana Platform plugins are pre-built with `@kbn/optimizer`
and distributed as package artifacts. This means that it is no
longer necessary for us to include the `optimizer` in the
longer necessary for us to include the `optimizer` in the
distributable version of Kibana Every plugin artifact contains all
plugin dependencies required to run the plugin, except some
stateful dependencies shared across plugin bundles via
stateful dependencies shared across plugin bundles via
`@kbn/ui-shared-deps-npm` and `@kbn/ui-shared-deps-src`. This means
that plugin artifacts _tend to be larger_ than they were in the
legacy platform. To understand the current size of your plugin
@ -101,7 +101,7 @@ node scripts/build_kibana_platform_plugins.js --dist --no-examples --profile
Many OSS tools allow you to analyze the generated stats file:
* [An official tool](https://webpack.github.io/analyse/#modules) from
Webpack authors
* [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/)
* [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)
- [An official tool](https://webpack.github.io/analyse/#modules) from
Webpack authors
- [webpack-visualizer](https://chrisbateman.github.io/webpack-visualizer/)
- [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)

27
dev_docs/key_concepts/persistable_state.mdx
View file

@ -1,19 +1,19 @@
---
id: kibDevDocsPersistableStateIntro
slug: /kibana-dev-docs/persistable-state-intro
slug: /kibana-dev-docs/key-concepts/persistable-state-intro
title: Persistable State
summary: Persitable state is a key concept to understand when building a Kibana plugin.
date: 2021-02-02
tags: ['kibana','dev', 'contributor', 'api docs']
tags: ['kibana', 'dev', 'contributor', 'api docs']
---
“Persistable state” is developer-defined state that supports being persisted by a plugin other than the one defining it. Persistable State needs to be serializable and the owner can/should provide utilities to migrate it, extract and inject any <DocLink id="kibDevDocsSavedObjectsIntro" section="references" text="references to Saved Objects"/> it may contain, as well as telemetry collection utilities.
“Persistable state” is developer-defined state that supports being persisted by a plugin other than the one defining it. Persistable State needs to be serializable and the owner can/should provide utilities to migrate it, extract and inject any <DocLink id="kibDevDocsSavedObjectsIntro" section="references" text="references to Saved Objects"/> it may contain, as well as telemetry collection utilities.
## Exposing state that can be persisted
Any plugin that exposes state that another plugin might persist should implement <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableStateService" text="`PersistableStateService`"/> interface on their `setup` contract. This will allow plugins persisting the state to easily access migrations and other utilities.
Example: Data plugin allows you to generate filters. Those filters can be persisted by applications in their saved
Example: Data plugin allows you to generate filters. Those filters can be persisted by applications in their saved
objects or in the URL. In order to allow apps to migrate the filters in case the structure changes in the future, the Data plugin implements `PersistableStateService` on <DocLink id="kibDataQueryPluginApi" section="def-public.FilterManager" text="`data.query.filterManager`"/>.
note: There is currently no obvious way for a plugin to know which state is safe to persist. The developer must manually look for a matching `PersistableStateService`, or ad-hoc provided migration utilities (as is the case with Rule Type Parameters).
@ -26,9 +26,10 @@ interface on their `setup` contract and each item in the collection should imple
Example: Embeddable plugin owns the registry of embeddable factories to which other plugins can register new embeddable factories. Dashboard plugin
stores a bunch of embeddable panels input in its saved object and URL. Embeddable plugin setup contract implements `PersistableStateService`
interface and each `EmbeddableFactory` needs to implement `PersistableStateDefinition` interface.
interface and each `EmbeddableFactory` needs to implement `PersistableStateDefinition` interface.
Embeddable plugin exposes this interfaces:
```
// EmbeddableInput implements Serializable
@ -45,7 +46,7 @@ If the state your plugin is storing can be provided by other plugins (your plugi
## Storing persistable state as part of saved object
Any plugin that stores any persistable state as part of their saved object should make sure that its saved object migration
Any plugin that stores any persistable state as part of their saved object should make sure that its saved object migration
and reference extraction and injection methods correctly use the matching `PersistableStateService` implementation for the state they are storing.
Take a look at [example saved object](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/server/searchable_list_saved_object.ts#L32) which stores an embeddable state. Note how the `migrations`, `extractReferences` and `injectReferences` are defined.
@ -58,13 +59,17 @@ of `PersistableStateService` should be called, which will migrate the state from
note: Currently there is no recommended way on how to store version in url and its up to every application to decide on how to implement that.
## Available state operations
### Extraction/Injection of References
In order to support import and export, and space-sharing capabilities, Saved Objects need to explicitly list any references they contain to other Saved Objects.
To support persisting your state in saved objects owned by another plugin, the <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableState.extract" text="`extract`"/> and <DocLink id="kibKibanaUtilsPluginApi" section="def-common.PersistableState.inject" text="`inject`"/> methods of Persistable State interface should be implemented.
<DocLink id="kibDevTutorialSavedObject" section="references" text="Learn how to define Saved Object references"/>
<DocLink
id="kibDevTutorialSavedObject"
section="references"
text="Learn how to define Saved Object references"
/>
[See example embeddable providing extract/inject functions](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/public/migrations/migrations_embeddable_factory.ts)
@ -72,7 +77,7 @@ To support persisting your state in saved objects owned by another plugin, the <
As your plugin evolves, you may need to change your state in a breaking way. If that happens, you should write a migration to upgrade the state that existed prior to the change.
<DocLink id="kibDevTutorialSavedObject" section="migrations" text="How to write a migration"/>.
<DocLink id="kibDevTutorialSavedObject" section="migrations" text="How to write a migration" />.
[See an example saved object storing embeddable state implementing saved object migration function](https://github.com/elastic/kibana/blob/master/examples/embeddable_examples/server/searchable_list_saved_object.ts)
@ -80,4 +85,4 @@ As your plugin evolves, you may need to change your state in a breaking way. If
## Telemetry
You might want to collect statistics about how your state is used. If that is the case you should implement the telemetry method of Persistable State interface.
You might want to collect statistics about how your state is used. If that is the case you should implement the telemetry method of Persistable State interface.

39
dev_docs/key_concepts/saved_objects.mdx
View file

@ -1,39 +1,42 @@
---
id: kibDevDocsSavedObjectsIntro
slug: /kibana-dev-docs/saved-objects-intro
slug: /kibana-dev-docs/key-concepts/saved-objects-intro
title: Saved Objects
summary: Saved Objects are a key concept to understand when building a Kibana plugin.
date: 2021-02-02
tags: ['kibana','dev', 'contributor', 'api docs']
tags: ['kibana', 'dev', 'contributor', 'api docs']
---
"Saved Objects" are developer defined, persisted entities, stored in the Kibana system index (which is also sometimes referred to as the `.kibana` index).
The Saved Objects service allows Kibana plugins to use Elasticsearch like a primary database. Think of it as an Object Document Mapper for Elasticsearch.
Some examples of Saved Object types are dashboards, lens, canvas workpads, index patterns, cases, ml jobs, and advanced settings. Some Saved Object types are
exposed to the user in the [Saved Object management UI](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html), but not all.
Some examples of Saved Object types are dashboards, lens, canvas workpads, index patterns, cases, ml jobs, and advanced settings. Some Saved Object types are
exposed to the user in the [Saved Object management UI](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html), but not all.
Developers create and manage their Saved Objects using the SavedObjectClient, while other data in Elasticsearch should be accessed via the data plugin's search
services.
![image](../assets/saved_object_vs_data_indices.png)
<DocLink id="kibDevTutorialSavedObject" text="Tutorial: Register a new Saved Object type"/>
<DocLink id="kibDevTutorialSavedObject" text="Tutorial: Register a new Saved Object type" />
## References
In order to support import and export, and space-sharing capabilities, Saved Objects need to explicitly list any references they contain to other Saved Objects.
The parent should have a reference to it's children, not the other way around. That way when a "parent" is exported (or shared to a space),
all the "children" will be automatically included. However, when a "child" is exported, it will not include all "parents".
all the "children" will be automatically included. However, when a "child" is exported, it will not include all "parents".
<DocLink id="kibDevTutorialSavedObject" section="references" text="Learn how to define Saved Object references"/>
<DocLink
id="kibDevTutorialSavedObject"
section="references"
text="Learn how to define Saved Object references"
/>
## Migrations and Backward compatibility
As your plugin evolves, you may need to change your Saved Object type in a breaking way (for example, changing the type of an attribtue, or removing
an attribute). If that happens, you should write a migration to upgrade the Saved Objects that existed prior to the change.
<DocLink id="kibDevTutorialSavedObject" section="migrations" text="How to write a migration"/>.
<DocLink id="kibDevTutorialSavedObject" section="migrations" text="How to write a migration" />.
## Security
@ -47,30 +50,30 @@ Saved Objects are "space aware". They exist in the space they were created in, a
Feature controls provide another level of isolation and shareability for Saved Objects. Admins can give users and roles read, write or none permissions for each Saved Object type.
### Object level security (OLS)
### Object level security (OLS)
OLS is an oft-requested feature that is not implemented yet. When it is, it will provide users with even more sharing and privacy flexibility. Individual
objects can be private to the user, shared with a selection of others, or made public. Much like how sharing Google Docs works.
## Scalability
By default all saved object types go into a single index. If you expect your saved object type to have a lot of unique fields, or if you expect there
to be many of them, you can have your objects go in a separate index by using the `indexPattern` field. Reporting and task manager are two
to be many of them, you can have your objects go in a separate index by using the `indexPattern` field. Reporting and task manager are two
examples of features that use this capability.
## Searchability
Because saved objects are stored in system indices, they cannot be searched like other data can. If you see the phrase “[X] as data” it is
Because saved objects are stored in system indices, they cannot be searched like other data can. If you see the phrase “[X] as data” it is
referring to this searching limitation. Users will not be able to create custom dashboards using saved object data, like they would for data stored
in Elasticsearch data indices.
## Saved Objects by value
Sometimes Saved Objects end up persisted inside another Saved Object. We call these Saved Objects “by value”, as opposed to "by
reference". If an end user creates a visualization and adds it to a dashboard without saving it to the visualization
library, the data ends up nested inside the dashboard Saved Object. This helps keep the visualization library smaller. It also avoids
issues with edits propagating - since an entity can only exist in a single place.
Note that from the end user stand point, we don’t use these terms “by reference” and “by value”.
reference". If an end user creates a visualization and adds it to a dashboard without saving it to the visualization
library, the data ends up nested inside the dashboard Saved Object. This helps keep the visualization library smaller. It also avoids
issues with edits propagating - since an entity can only exist in a single place.
Note that from the end user stand point, we don’t use these terms “by reference” and “by value”.
## Sharing Saved Objects
@ -80,7 +83,7 @@ on how it is registered.
If you are adding a **new** object type, when you register it:
1. Use `namespaceType: 'multiple-isolated'` to make these objects exist in exactly one space
2. Use `namespaceType: 'multiple'` to make these objects exist in one *or more* spaces
2. Use `namespaceType: 'multiple'` to make these objects exist in one _or more_ spaces
3. Use `namespaceType: 'agnostic'` if you want these objects to always exist in all spaces
If you have an **existing** "legacy" object type that is not shareable (using `namespaceType: 'single'`), see the [legacy developer guide