docs/extend/saved-objects.md
Saved Objects allow {{kib}} plugins to use {{es}} like a primary database. Think of them as an Object Document Mapper for {{es}}. Once a plugin has registered one or more Saved Object types, the Saved Objects client can be used to query or perform create, read, update and delete operations on each type.
Terminology: A Saved Object type is the schema and configuration that a plugin registers for a kind of document (name, mappings, model versions, etc.). Saved Objects are the document instances of that type stored in {{es}}. The sections below cover both how to define and evolve Saved Object types and how to perform CRUD on Saved Object instances via the Core service (see Use).
::::{note} The Saved Objects service is available on server side. Client side services and APIs have been deprecated for some time and will be removed in the near future. ::::
By using Saved Objects your plugin can take advantage of the following features:
hidden=true is specified).references, an object's entire reference graph will be exported. This makes it easy for users to export e.g. a dashboard object and have all the visualization objects required to display the dashboard included in the export.:::::{important}
When integrating with saved objects via the Saved Objects import/export APIs or the deprecated Saved Objects HTTP CRUD APIs, preserve coreMigrationVersion and typeMigrationVersion when persisting raw saved object documents outside of Kibana (for example, in JSON/NDJSON files). These fields are required to retain forwards compatibility across Kibana versions as saved object types evolve.
:::::
Saved Objects are secured using Kibana's privileges model, unlike data in {{es}} data indices, which is secured using {{es}}'s model.
Saved Objects are "space aware". Each object exists in the space it was created in, and any additional spaces it has been shared with. See Share across spaces for details.
Feature controls provide another level of isolation for Saved Objects. Admins can grant users and roles read, write, or no access to each Saved Object type independently.
OLS is a planned feature, not yet implemented. Once available, it will allow individual objects to be private to their owner, shared with selected users, or made fully public — similar to how sharing in Google Docs works.
By default all Saved Object types share the same index. If you expect a type to have many unique fields or a large number of instances, store it in a dedicated index by setting the indexPattern field when registering the type. Reporting and Task Manager both use this capability.
Saved Objects are stored in system indices and cannot be searched like regular {{es}} data. If you see the phrase "[X] as data", it refers to this limitation: users cannot build custom dashboards or visualizations over Saved Object data the way they can with data in ordinary {{es}} indices.
A Saved Object can be embedded inside another Saved Object ("by value") rather than saved as a standalone item ("by reference"). For example, when a user adds a visualization to a dashboard without saving it to the library, the visualization data is nested inside the dashboard Saved Object. This keeps the library smaller and avoids unexpected propagation of edits, since the embedded object exists in exactly one place.
Note: the terms "by value" and "by reference" are internal developer concepts and are not surfaced to end users.
This documentation is organized into the following sections: